docs: Cloudflare Workers transition design (companion to #11)

[zmuhls]

Summary

Adds docs/superpowers/specs/2026-09-03-cloudflare-transition-design.md, a design proposal that pairs with the unified architecture spec in #11. Where #11 makes the app portable (one core, thin hosts), this document chooses the host: one Cloudflare Worker behind the lab's CUNY-login doorway, with model access through the lab's model gateway, configured the way the lab's own apps are configured today.

What it proposes

• Host: one Worker (cail-slide-maker) serving the SvelteKit adapter-static build as assets and the Hono API, path-mounted behind cail-doorway at tools.ailab.gc.cuny.edu/slide-maker/ (the app already implements that base path). Deployed with Wrangler from GitHub Actions; staging and production Workers; release stamped at deploy.
• Identity: doorway-issued x-cail-identity-jwt per request, verified with @cuny-ai-lab/cail-identity; users keyed by cail- subject; admission is the allow-list. Deletes registration, verification email, admin approval, password reset, argon2, Lucia sessions, and SES. Includes a one-time legacy claim for existing accounts and share-by-name / capability links (the identity carries no email).
• Model access: a GATEWAY service binding to cail-model-api with the doorway-minted gateway JWT as bearer, x-cail-app and x-cail-session-id headers, model list from /v1/models filtered by function-calling capability, usage from the stream, budgets enforced by the gateway's per-person spend limits. No provider keys in the app. Direct Anthropic/Bedrock/OpenRouter adapters remain for local development only.
• State: one SQLite Durable Object per deck (document, mutation log, lock, presence, WebSocket fan-out) on top of the docs: add unified architecture design spec (2026-09-03) #11 reducer; D1 for account tables; R2 for uploads; Rate Limiting bindings keyed by subject; env.AI.toMarkdown() for PDF/DOCX extraction; fflate for export.
• Kale Deploy: documented as not applicable for the app under its current release contract (no bindings, 2 MiB source artifacts, no public hostname yet). Published decks go to an R2 bucket with a public custom domain instead of the GitHub-backed Kale project planned in April.
• Six-phase migration, the first two of which run on the current Node host.

Sources

Read from the deployed Worker bundles on the CUNY AI Lab Cloudflare account on 2026-09-03 (cail-cadavre, cail-model-api, cail-model-access-api, cail-doorway, cail-tools-admission, cail-deploy-service, agent-studio) and from the cail-doorway, cail-deploy, and cail-identity repositories. The spec states where something could not be determined from those sources.

Relationship to #11

#11 is the precondition: the reducer and document make the deck Durable Object a thin shell, the render package makes SSR export host-neutral, and the AI package's event contract is what the gateway adapter implements. The two can be reviewed independently and land in order.

This is a proposal document for discussion and planning; no code changes are included.

🤖 Generated with Claude Code

https://claude.ai/code/session_015B7qW78KqCz7p1Po2Q9bXE

---

Generated by Claude Code

[szweibel]

Two platform assumptions need correction before this becomes an accepted implementation plan. The existing SSRF guard uses node:dns/promises.lookup, which Workers documents as unimplemented; it cannot move unchanged under nodejs_compat (https://developers.cloudflare.com/workers/runtime-apis/nodejs/dns/). Rate Limiting bindings are per Cloudflare location and permissive/eventually consistent, not a global hard limit (https://developers.cloudflare.com/workers/runtime-apis/bindings/rate-limit/). Also resolve mutation-log version PRIMARY KEY versus the companion design incrementing version once per multi-mutation batch. The proposed local admin-subject list needs reconciliation with Admission-owned administrator authorization. This is a design review, not approval for account migration, infrastructure changes, or deployment.

[zmuhls]

Revised in 89af32f to address the review:

• SSRF guard. Confirmed against the Workers node:dns docs: resolve4/resolve6 work over DoH but lookup, lookupService, and resolve throw "Not implemented". New §2.10 rewrites the guard on resolve4 + resolve6 (both record types, any private answer rejected, second resolution compared for rebinding), keeps redirect: 'manual' and the timeout, and states plainly that neither host can pin the connection (the current Node code never used the resolvedIp it returns). The "same code" row in §2.6 and the "unchanged" list in §5 are corrected.
• Rate Limiting bindings. §2.1, §2.2, and §2.10 now describe them as per-location and approximate, used as throttles only. Every limit that must be exact is listed with the strongly consistent store that enforces it: chat spend at the gateway, file/deck size sums inside the D1 upload transaction, slide cap / lock / baseVersion inside DeckRoom.apply.
• Version semantics. The per-mutation mutations (version INTEGER PRIMARY KEY, mutation, inverse) table is gone. DeckRoom now stores commits (version INTEGER PRIMARY KEY, base_version, mutations, inverses, …), one row per batch, version incremented once per commit, matching docs: add unified architecture design spec (2026-09-03) #11 §2.2 (revised in the same pass) word for word.
• Admin authorization. SLIDE_MAKER_ADMIN_SUBJECTS is removed. Admin requests call admission's AdmissionResolver.resolveMembership({ subject }) over an ADMISSION service binding and require accessRole === 'admin'; nothing is cached or stored, so revocation is immediate. Binding the resolver is a request to admission's stewards made with the doorway route; if declined, the app ships with no admin surface and the two admin functions become operator scripts.
• Review scope. The header states this is a design for review, not approval for account migration, infrastructure changes, or deployment, and §3 names the approval each phase needs.

---

Generated by Claude Code

[szweibel]

Reviewed the revision at 89af32f. The DNS compatibility and Rate Limiting descriptions now address the earlier findings. Administrator authorization defers to Admission with an explicit steward decision on the binding and an operator-script alternative; the ordinary batch-log semantics now match #11.

One identity-transition gap remains, noted inline: the limits table says there are no passwords, but the legacy claim still verifies an old password during the grace period. Please specify claim-specific attempt controls through retirement, or use operator-only linking. Companion #11 also needs its import/version collision resolved.

This is review of the revised design and earlier findings, not migration execution or deployed acceptance. The next step is the proposal author's revision. Acceptance of an Admission binding and any infrastructure or data migration remain separate decisions.

[szweibel]

[P2] Retain attempt controls for the legacy password claim. Line 227 keeps an email/password verification path for linking old accounts during the grace period. An admitted user can therefore still guess another legacy account's password; CUNY sign-in does not remove that target. Specify claim-specific attempt controls until the path is retired, or choose the operator-only linking route, and make this table agree with that decision.

[szweibel]

Closing as superseded. #15/#16 continue on the Node host; the identity and admin issues raised here are covered in the #13 reconciliation that lands through #15. The proposal stays readable here as design history.