Goal: Harden the Cubid SDK for the production Identity issuer

[KazanderDad]

Parent: https://github.com/Cubid-Me/cubid-monorepo/issues/49
Brainstorm Task: Capture production SIWC hosted-test evidence and narrowing
Sequence: Goal 2 of 3

Objective

Make the canonical public SDK fail closed against an unavailable or inconsistent production issuer and provide release-grade acceptance evidence for https://id.cubid.me.

Execution Tasks

• Add production discovery/JWKS/issuer readiness gates.
• Harden environment-specific docs, examples, and mismatch coverage across the auth packages.

Sequence Context

• Previously blocked by: the monorepo production protocol boundary Goal. This blocker is satisfied by Cubid monorepo #51 and #54 reaching On dev.
• Enables: the starter deployment and full relying-party smoke Goal.
• Run independently by: a fresh Codex thread in Cubid-Me/cubid-sdk now that the production issuer handoff is reachable.

Non-Goals

• Runtime/Identity implementation.
• Silent fallback from production to staging.
• Publishing a release without separate release-promotion approval.

Guardrails

• Keep strict ID-token issuer and audience validation.
• Keep secrets and client credentials out of browser packages and examples.
• Use dedicated @cubid/auth and @cubid/auth-react ownership.
• Evaluate any protocol-shape change against the private monorepo first.

Expected Codebase Surfaces

• packages/auth/**, packages/auth-react/**, and packages/acceptance/**.
• Root/package READMEs and CI workflows.
• Repo branch session log and cross-repo issue links.

Acceptance Criteria

• Production readiness checks detect DNS, discovery, JWKS, endpoint, and issuer mismatches.
• Staging remains explicit and cannot be selected as an implicit production fallback.
• Documentation and examples present consistent production/staging configuration.
• Relevant package tests and acceptance suites pass.

Validation Plan

Run focused auth tests, acceptance tests, repo lint/typecheck/build, and live production metadata probes without exchanging user credentials.

Child Tasks

• SDK-01 Add a production Identity issuer readiness gate
• SDK-02 Align production and staging auth guidance with strict issuer validation — blocked by SDK-01

Risks And Mitigations

• Hosted issuer may regress after validation: automate recurring smoke and fail release promotion.
• Strict checks may surface existing consumer misconfiguration: document remediation rather than weakening validation.

Stop Condition

Stop when SDK changes are committed and independently validated against the live production issuer, with no package publication performed unless separately approved.

Vetting Addendum — 2026-07-16

Implementation Worktree

• Repo: Cubid-Me/cubid-sdk
• Worktree: /Users/botmaster/src/cubid/cubid-sdk-sprint-49-production-issuer
• Branch: codex/sprint-49-production-issuer
• Base: dev
• Shared by: SDK-01 Add a production Identity issuer readiness gate #36 and SDK-02 Align production and staging auth guidance with strict issuer validation #37; run sequentially.
• Retain until the source branch PR into dev is merged and validation is complete.
• Cleanup owner: sprint-orchestrator via $approved-cleanup.

Before creating this worktree, fetch origin/dev; the existing /Users/botmaster/src/cubid/cubid-sdk checkout is a stale shallow legacy checkout and is not the implementation surface. Use the canonical monorepo package structure from origin/dev. Update code, technical docs, tests, CI, and the branch-scoped session log as required.

Integrated validation and smoke

Run the canonical origin/dev lint, typecheck, test, build, and acceptance commands discovered from that branch. Then run the metadata-only readiness command against production and explicit staging fixtures, proving exact issuer equality, discovery/JWKS reachability, supported PKCE/code flow, mismatch failures, and no implicit fallback. No UI visual evidence is required for this SDK-only Goal.

Issue Validator

After both Tasks, local/live validation, session-log updates, and commits, run $issue-validator before moving this Goal to In Review. Provide the Goal/Sprint URLs, commits, worktree, changed files, commands/results, metadata smoke results, non-goals, and Visual evidence: N/A. The validator checks strict issuer/audience behavior, failure fixtures, release-gate wiring, docs/examples consistency, no legacy-checkout contamination, and boundary compliance; reports pass, pass-with-notes, or fail to sprint-orchestrator; and comments here. A fail returns the relevant Task to implementation.

Stop at In Review; do not publish packages.

[KazanderDad]

Goal validation evidence

SDK Goal #35 is implemented on branch codex/sprint-49-production-issuer with two commits:

• 1abb7984 - production Identity issuer readiness gate for @cubid/auth
• 46bb060c - production/staging auth guidance alignment across auth/auth-react/examples/tests

Acceptance coverage

• Production readiness detects discovery/JWKS availability, exact issuer equality, authorization-code support, PKCE S256, and pairwise subject metadata.
• Staging is explicit: https://staging-id.cubid.me without environment: "staging" fails closed.
• Auth docs and examples now teach OIDC discovery from the configured issuer instead of hard-coded issuer-relative endpoint paths.
• React docs clarify https://login.cubid.me as compatibility UI, not the issuer value for new integrations.
• Consumer acceptance covers production readiness and explicit staging React configuration.
• Starter handoff posted to Goal: Deploy and prove the canonical Cubid starter integration cubid-starter-v3#1 (comment).

Validation run

• pnpm install --frozen-lockfile - passed earlier to repair the fresh worktree dependency graph.
• rg -n "https://id\\.cubid\\.me/authorize|login\\.cubid\\.me|staging-id\\.cubid\\.me" README.md docs packages --glob '!docs/reference/api/*.json' - audited; remaining matches are tests or explicit compatibility/staging guidance.
• pnpm --filter @cubid/auth build - passed
• pnpm --filter @cubid/auth-react build - passed
• pnpm exec vitest run --config vitest.config.ts packages/auth/src/index.test.ts packages/auth-react/src/index.test.tsx - 34 tests passed
• pnpm build - passed
• pnpm test:acceptance - 8 files / 12 tests passed
• pnpm docs:api:build - passed
• pnpm docs:api:check - passed
• pnpm auth:issuer:check - passed against https://id.cubid.me, JWKS keys: 1
• pnpm auth:issuer:check -- --environment staging --issuer https://staging-id.cubid.me - passed against explicit staging, JWKS keys: 1
• pnpm lint - passed
• pnpm typecheck - passed
• git diff --check - passed

Non-goals preserved

• No Identity runtime changes.
• No silent fallback from production to staging.
• No Passport/Admin/Verify/internal OIDC route dependency added.
• No user login, authorization-code exchange, or package publication performed.
• Visual evidence: N/A for this SDK metadata/docs/test Goal.

Result: pass-with-notes. The branch is ready for GitHub review into dev; package publication remains deferred until separate release approval.