# Release Readiness Checklist This checklist is the production release gate for `@tidbcloud/auth-js`. A release candidate is ready only when every required item is checked with evidence from the exact candidate commit or package artifact. Do not publish on intent, partial local state, or unreviewed generated output. ## Release Scope - Package: `@tidbcloud/auth-js` - SDK root: `tidbcloud-auth-js/` - Service contract source: `tidbcloud-auth/internal/tidbrest/testdata/sdk_requests/` - Product model: TiDB-native Supabase-like application SDK - Compatibility model: Supabase-like ergonomics, not `supabase-js` compatibility - Public API scope: Auth-aware published Data API client, runtime entry policies, schema/typegen entry points, documented type model ## Non-Negotiable Boundaries The release must not include public SDK support for: - raw SQL - arbitrary query execution - DDL - DCL - grant or revoke - schema mutation through public Data API - SQL console - RPC, procedures, routines, or function execution - admin, system, MCP, UI, or dashboard routes - transaction scripting - PostgreSQL `RETURNING` - PostgreSQL RLS compatibility - PostgREST grammar compatibility - direct TiDB introspection from application SDK code - browser service-key usage ## Required Evidence Record the following evidence before publishing: - candidate commit SHA - package version - package tarball filename - package tarball checksum - service fixture checksum lines - Node.js and npm versions - OS/runtime used for release checks - full command output location or CI run URL - reviewer names or approval IDs ## Gate 1: Source And Scope - [ ] Candidate branch contains only intended SDK and documentation changes. - [ ] `tidbcloud-auth-js/README.md` describes the SDK as TiDB-native Supabase-like, not `supabase-js` compatible. - [ ] `tidbcloud-auth-js/docs/api-reference.md` matches public exports and implemented behavior. - [ ] `tidbcloud-auth-js/docs/migration-supabase-js.md` documents non-drop-in migration and unsupported PostgreSQL/PostgREST features. - [ ] `tidbcloud-auth-js/docs/troubleshooting.md` covers contract, auth, unsupported operation, redaction, and dry-pack failures. - [ ] `tidbcloud-auth-js/docs/security.md` describes runtime boundaries, credential classes, redaction, and forbidden capabilities. - [ ] All examples use placeholders, not live credentials. ## Gate 2: Service Contract Baseline Run from repository root: ```sh cd tidbcloud-auth GOCACHE=/private/tmp/supabase-like-go-build-cache go test ./internal/tidbrest -run 'TestSDKRequestFixturesCoverPositiveContract|TestNegativeRequestFixturesReturnStableErrors|TestCompatibilityRequestFixturesCoverStableRoutesErrorsAndAuthHeaders|TestOpenAPISDKSecurityModeFixtures' -count=1 -v ``` Required: - [ ] positive fixtures cover allowed published Data API requests. - [ ] negative fixtures cover forbidden capabilities with stable errors. - [ ] compatibility fixtures cover auth header and route errors. - [ ] security mode fixtures keep service mode server-side only. - [ ] no service code change is required for SDK release. ## Gate 3: Fixture Sync Run: ```sh cd tidbcloud-auth-js npm run sync:fixtures npm run test:contracts ``` Required: - [ ] generated SDK fixtures match service fixtures. - [ ] generated fixture checksums are current. - [ ] positive builder output matches service positive fixtures. - [ ] reverse scans reject forbidden routes and headers. - [ ] fixture diffs are reviewed and explained. ## Gate 4: Typecheck And Build Run: ```sh cd tidbcloud-auth-js npm run typecheck npm run build npm run test:types ``` Required: - [ ] TypeScript source typechecks. - [ ] production build succeeds. - [ ] generated declarations match public API expectations. - [ ] type tests reject unknown tables, unknown columns, invalid payloads, and unsupported helpers. ## Gate 5: Unit And Integration Behavior Run: ```sh cd tidbcloud-auth-js npm test ``` Required: - [ ] Data builders are immutable. - [ ] request descriptors match documented routes. - [ ] `PATCH` and `DELETE` require filters. - [ ] unsupported select grammar fails locally. - [ ] Auth-aware execution sends `apikey` and bearer headers when configured. - [ ] normalized errors preserve status and request ids. - [ ] retry behavior does not replay unsafe mutations by default. ## Gate 6: Security - [ ] `session_database_changed` clears only the matching persisted session, stops refresh, broadcasts `SIGNED_OUT`, and is not retried. - [ ] Network failures, `5xx` responses, and ordinary `403` policy errors do not clear the session. - [ ] Browser, server, edge, and package exports contain no Admin binding, replacement, DSN, service-key, or database-selection API. Run: ```sh cd tidbcloud-auth-js npm run test:security ``` Required: - [ ] browser entry exposes no service-key helper. - [ ] server service-key policy is server-entry only. - [ ] service security fixture is server-side only. - [ ] redaction covers headers, URLs, nested bodies, errors, logger payloads, and hook payloads. - [ ] no docs example contains live credentials. ## Gate 7: Exports And Runtime Boundaries Run: ```sh cd tidbcloud-auth-js npm run test:exports npm run test:bundle ``` Required: - [ ] root export resolves to documented public API. - [ ] browser export resolves without server-only helpers. - [ ] server export is not imported by browser bundle tests. - [ ] edge export avoids Node-only assumptions. - [ ] schema and typegen entries are documented and resolve as intended. - [ ] bundle scan contains no service-key strings, admin helpers, RPC helpers, raw SQL helpers, or server-only secrets. ## Gate 8: Package Artifact Run: ```sh cd tidbcloud-auth-js npm run pack:dry-run ``` Required: - [ ] tarball contains `dist/`, `README.md`, `LICENSE`, `package.json`, and required docs. - [ ] tarball excludes `src/`, `test/`, local caches, `.DS_Store`, live fixtures with secrets, and unrelated planning artifacts. - [ ] tarball allowlist is reviewed. - [ ] package checksum is recorded. - [ ] package metadata points to the correct runtime entries and declaration files. Required docs in tarball: - [ ] `docs/api-reference.md` - [ ] `docs/migration-supabase-js.md` - [ ] `docs/troubleshooting.md` - [ ] `docs/security.md` - [ ] `docs/release-checklist.md` If package metadata omits any required doc, do not publish. Update packaging configuration in a separate scoped change and rerun this gate. ## Gate 9: API And Semver Review Required: - [ ] public exports are reviewed against API reference. - [ ] unsupported public helpers remain absent. - [ ] breaking changes are identified and documented. - [ ] version bump follows semver. - [ ] migration notes cover user-visible behavior changes. - [ ] deprecations, if any, include replacement guidance. ## Gate 10: Documentation Review Required: - [ ] README states positioning, install, quick start, forbidden capabilities, and release status. - [ ] API reference includes all public entries and response/error shapes. - [ ] migration guide clearly states non-drop-in behavior. - [ ] troubleshooting includes service contract and security failures. - [ ] security doc includes credential classes and runtime boundaries. - [ ] release checklist has current commands and evidence fields. ## Gate 11: Dependency And Supply Chain Required: - [ ] lockfile is current for the release candidate. - [ ] dependency audit policy has been applied. - [ ] production dependency surface is reviewed. - [ ] generated artifacts are reproducible from source. - [ ] provenance or SBOM requirements are satisfied if required by the release channel. ## Gate 12: Final Approval Required: - [ ] release owner signs off. - [ ] security reviewer signs off. - [ ] API reviewer signs off. - [ ] docs/release readiness reviewer signs off. - [ ] CI or local evidence is linked. - [ ] release notes are prepared. - [ ] rollback plan is recorded. ## Release Decision Mark exactly one: - [ ] Approved for production release. - [ ] Blocked by contract mismatch. - [ ] Blocked by security boundary failure. - [ ] Blocked by package artifact contents. - [ ] Blocked by docs/API mismatch. - [ ] Blocked by incomplete tests. - [ ] Blocked by reviewer concern. ## Post-Release Checks After publishing: - [ ] install package from registry in a clean project. - [ ] verify root, browser, server, edge, schema, and typegen imports. - [ ] run a smoke Data API request against a non-production test service. - [ ] verify published tarball contents match dry-pack evidence. - [ ] monitor auth, contract, and unsupported-operation support tickets. - [ ] record any follow-up fixes in the next release plan.