onenote-prod-checklist

What this skill does

# OneNote Production Checklist

## Overview

OneNote integrations that work perfectly in development break in production in predictable ways: SharePoint document libraries exceed the 5,000-item view threshold and stop returning notebooks, image uploads silently truncate above 4MB, rate limits compound across users during business hours, and MSAL token caches lose state across container restarts. This skill is a comprehensive go/no-go checklist organized by failure category. Each item references the specific Graph API behavior that causes the production failure and provides the fix. Use this checklist during launch reviews — every unchecked item is a production incident waiting to happen.

## Prerequisites

- A functional OneNote integration that works in development/staging
- Azure AD app registration with delegated permissions configured
- Access to production monitoring infrastructure (logging, alerting)
- Familiarity with your deployment environment (containers, VMs, serverless)
- Completed `onenote-security-basics` and `onenote-rate-limits` skills

## Instructions

### 1. Authentication Checklist

| # | Check | Why it matters |
|:-:|-------|---------------|
| 1.1 | Using delegated auth (DeviceCodeCredential or InteractiveBrowserCredential) | App-only auth (ClientSecretCredential) deprecated for OneNote March 31, 2025 |
| 1.2 | MSAL token cache serialized to persistent storage | Container restarts lose in-memory cache; users forced to re-authenticate |
| 1.3 | Silent token renewal tested (call `acquire_token_silent` before every request) | Access tokens expire in 1 hour; without silent renewal, users hit 401 hourly |
| 1.4 | Refresh token 90-day expiry monitored | Inactive users' refresh tokens expire silently; need re-auth flow |
| 1.5 | Token cache file permissions set to 0600 (owner-only) | Cache contains refresh tokens — world-readable is a credential leak |
| 1.6 | Multi-tenant: `tid` claim validated on every token | Prevents cross-tenant data leakage from token reuse |

**Verification test:**

```python
import os, time

def verify_auth_resilience(client):
    """Test that auth survives token expiry cycle."""
    # 1. Make a call to confirm auth works
    response = client.me.onenote.notebooks.get()
    assert response.value is not None, "Initial auth failed"

    # 2. Verify token cache exists on disk
    cache_path = os.path.expanduser("~/.onenote-token-cache.json")
    assert os.path.exists(cache_path), "Token cache not persisted"
    stat = os.stat(cache_path)
    assert oct(stat.st_mode)[-3:] == "600", f"Cache permissions {oct(stat.st_mode)} not 600"

    # 3. Verify silent renewal works (simulate expired access token)
    response2 = client.me.onenote.notebooks.get()
    assert response2.value is not None, "Silent renewal failed"
    print("Auth resilience: PASS")
```

### 2. Rate Limit Checklist

| # | Check | Why it matters |
|:-:|-------|---------------|
| 2.1 | Retry-After header parsed and honored on 429 responses | Ignoring Retry-After escalates throttling duration |
| 2.2 | Exponential backoff implemented (not fixed delay) | Fixed delays waste time on short throttles, not enough on long ones |
| 2.3 | Per-user call tracking in place | One power user can consume the entire 600/min budget |
| 2.4 | Tenant-level rate tracked (10,000/10min across all users) | Dev testing per-user never reveals the tenant ceiling |
| 2.5 | Queue-based throttling for batch operations | Bursting 200 requests fails; queuing 20/second succeeds |
| 2.6 | 429 alert configured (threshold: >1% of requests) | Early warning before users notice degradation |

**Retry-After implementation:**

```typescript
async function callWithRetry(
  client: any,
  apiPath: string,
  maxRetries: number = 3
): Promise<any> {
  for (let attempt = 0; attempt <= maxRetries; attempt++) {
    try {
      return await client.api(apiPath).get();
    } catch (error: any) {
      if (error.statusCode === 429 && attempt < maxRetries) {
        const retryAfter = parseInt(error.headers?.["retry-after"] || "5", 10);
        console.warn(
          `Rate limited. Retry-After: ${retryAfter}s (attempt ${attempt + 1}/${maxRetries})`
        );
        await new Promise((resolve) => setTimeout(resolve, retryAfter * 1000));
      } else {
        throw error;
      }
    }
  }
}
```

### 3. Error Handling Checklist

All seven Graph API error codes must have explicit handlers:

| # | Code | Handler required |
|:-:|:----:|-----------------|
| 3.1 | `400 Bad Request` | Validate XHTML before sending; log request body for debugging |
| 3.2 | `403 Forbidden` | Check scope in token; detect app-only auth usage; surface to user as "permissions needed" |
| 3.3 | `404 Not Found` | Handle deleted notebooks/sections/pages gracefully; clear local cache entry |
| 3.4 | `429 Too Many Requests` | Retry with Retry-After header (see section 2) |
| 3.5 | `500 Internal Server Error` | Retry with exponential backoff; log `request-id` header for Microsoft support |
| 3.6 | `502 Bad Gateway` | Retry once; if persistent, check for expired token edge case |
| 3.7 | `507 Insufficient Storage` | Section page limit hit; alert admin; suggest archival |

**Critical: Always log the `request-id` response header.** Microsoft support requires this for incident investigation:

```python
import logging

logger = logging.getLogger("onenote")

async def safe_api_call(client, api_path: str):
    try:
        return await client.api(api_path).get()
    except Exception as e:
        request_id = getattr(e, "headers", {}).get("request-id", "unknown")
        logger.error(
            f"Graph API error: {e} | path={api_path} | request-id={request_id}"
        )
        raise
```

### 4. Content Validation Checklist

| # | Check | Why it matters |
|:-:|-------|---------------|
| 4.1 | HTML validated as XHTML before POST (all tags closed, UTF-8) | Graph API silently strips invalid HTML — pages render incorrectly with no error |
| 4.2 | Page content size checked (< 4MB per page) | Oversized content silently truncates or returns 400 |
| 4.3 | Image format validated (PNG, JPEG, GIF only) | Unsupported formats (WebP, AVIF) silently fail |
| 4.4 | Image size checked (< 10MB per image) | Large images cause timeout during page creation |
| 4.5 | Embedded file count checked (< 10 per page) | Too many attachments cause 507 errors |

**XHTML validation before send:**

```python
from html.parser import HTMLParser

SELF_CLOSING_TAGS = {"br", "hr", "img", "input", "meta", "link"}

class XHTMLValidator(HTMLParser):
    def __init__(self):
        super().__init__()
        self.errors = []
        self.open_tags = []

    def handle_starttag(self, tag, attrs):
        if tag not in SELF_CLOSING_TAGS:
            self.open_tags.append(tag)

    def handle_endtag(self, tag):
        if tag in SELF_CLOSING_TAGS:
            return
        if not self.open_tags or self.open_tags[-1] != tag:
            self.errors.append(f"Mismatched close tag: </{tag}>")
        else:
            self.open_tags.pop()

    def validate(self, html: str) -> list[str]:
        self.feed(html)
        if self.open_tags:
            self.errors.append(f"Unclosed tags: {self.open_tags}")
        return self.errors

def validate_page_content(html_body: str) -> tuple[bool, list[str]]:
    """Validate content before sending to OneNote API."""
    issues = []

    # Size check
    size_bytes = len(html_body.encode("utf-8"))
    if size_bytes > 4 * 1024 * 1024:
        issues.append(f"Content too large: {size_bytes / 1024 / 1024:.1f}MB (max 4MB)")

    # XHTML validation
    validator = XHTMLValidator()
    html_errors = validator.validate(html_body)
    issues.extend(html_errors)

    return len(issues) == 0, issues
```

### 5. SharePoint-Specific Checklist

| # | Check | Why it matters |
|:-:|-------|---------------|
| 5.1 | Site-id resolved via Graph API (not hardcoded) | Site-ids change when sites are recreated or migrated |
| 5.2 | Document library item count monitored | Libra