@tktchurch/auth 0.9.1

package/CHANGELOG.md

@@ -0,0 +1,210 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## [0.9.1] - 2026-06-25
+
+### Changed
+
+- Dual-build pipeline: public npmjs publishes a **consumer** SDK (OAuth/OIDC client
+  namespaces only); GitHub Packages publishes the **full** internal SDK with admin
+  console modules, `request`/`fetchWithAuth`, and source maps.
+- Public consumer build is minified, ships without source maps, and does not export
+  `DEFAULT_BASE_URL` or admin TypeScript types.
+- `package.json` repository metadata now points at `tktchurch/auth-sdk-js`.
+
+### Added
+
+- `build:consumer`, `build:full`, `release:check:consumer` scripts.
+- `tests/consumer-build.test.ts` guards the public artifact surface.
+
+## [0.8.0] - 2026-06-24
+
+### Changed
+
+- `accounts/` and `developers/` Nuxt server utilities now use `@tktchurch/auth` for
+  PKCE authorization start, token exchange/refresh/revoke, user profile fetch, and
+  `sanitizePostAuthRedirect`.
+- Privacy UI stub pages: accounts `/account/privacy`, developers `/admin/privacy`
+  (hook points for upcoming `auth.privacy.*`).
+
+## [0.6.0] - 2026-06-24
+
+### Added
+
+- Platform modules: `families.*`, `dependents.*` (guardian consent), `clients.providers.*`.
+- Client API keys: `clients.apiKeys.list/create/delete` backed by new OAuth
+  `GET/POST/DELETE /api/v1/clients/:id/api-keys` routes.
+- OAuth backend admin reads: `GET /api/v1/users/:id/mfa/devices`,
+  `GET /api/v1/users/:id/webauthn/credentials`, and `GET /api/v1/sessions?user_id=`
+  for console user detail pages.
+
+### Tests
+
+- Unit coverage in `tests/phase051-platform.test.ts`; extended local-stack and Playwright suites.
+
+## [0.5.2] - 2026-06-24
+
+### Added
+
+- `clients.apiKeys.*` SDK methods (see 0.6.0 backend implementation).
+
+## [0.5.1] - 2026-06-24
+
+### Added
+
+- Migration parity: `oauth.discoverAuthorizationServer()`, `authorize.probeAuthorize()`,
+  `user.uploadAvatar()`, `memberDirectory.lookup()`, `federated.*` URL builders and
+  link finalize HTTP methods.
+- Admin reads: `user.admin.getMfaDevices()`, `user.admin.getWebAuthnCredentials()`.
+- List filter wiring: `clients.list({ isActive })`, expanded `UserListQuery`,
+  `RoleListQuery`, `SessionListQuery`, `AuditLogListQuery`.
+
+### Changed
+
+- `webauthn.removeCredential` accepts optional `{ password }` body.
+- `http.ts` supports `FormData` multipart uploads and `redirect: manual`.
+- README: `sessions.revokeOthers` → `revokeAll`.
+
+## [0.5.0] - 2026-06-24
+
+### Added
+
+- **Full API parity** with the TKTChurch OAuth backend — user-facing and admin
+  console surfaces used by `accounts` / `developers`.
+- User modules: `authorize.consent` / `consentWithCredentials`, `oidc.jwks`,
+  `token.tokenExchange` (RFC 8693), `flow.initRecovery` / `executeRecoveryStep`,
+  `passwordReset.*`, `mfa.*`, `user` self-service (`updateMe`, `changePassword`,
+  recovery contacts, identities), `consents.me.*`, `maintenance.status`,
+  `oauth.publicClient`.
+- Admin modules: `clients`, `scopes`, `roles`, `permissions`, `organizations`,
+  `auditLogs`, `dashboard`, `jwtKeys`, `webhooks`, `customAttributes`,
+  `authMethods`, `authenticationFlows`, `comms` (SMS/email providers, templates,
+  logs, test phones), and `user.admin` CRUD.
+- Shared pagination helpers (`normalizePageQuery`, `buildQueryString`,
+  `mapPageResponse`) with `MAX_PER_PAGE` cap.
+- Unit tests for all new modules; example smoke tests for PKCE route helpers;
+  gated local-stack integration tests (`bun run test:local`).
+
+### Changed
+
+- `token.revoke` and `token.introspect` now include `client_id` / `client_secret`
+  in the request body (required by the OAuth server for RFC 7009 / introspection).
+
+### Added (0.5.0 continued)
+
+- Expanded local-stack integration tests: PKCE full cycle, OIDC/JWKS, flow init,
+  public client metadata.
+- Playwright API e2e suite (`tests/e2e/`) for live backend + security invariants.
+- `bun run test:local:env` and `bun run test:e2e:env` scripts (source `oauth/.env`).
+
+
+### Verified
+
+- `bun run release:check` (74 unit tests + 6 gated integration tests)
+
+## [0.4.0] - 2026-06-24
+
+### Removed (breaking)
+
+- `createLocalStorageTokenStorage` and the `@tktchurch/auth/storage/localStorage`
+  package subpath. Browser `localStorage` is an XSS sink for OAuth tokens; the
+  SDK no longer ships a persistence adapter for it.
+
+### Added
+
+- Token storage validation exports: `assertValidAuthTokens`, `parseStoredAuthTokens`,
+  `serializeAuthTokens`, `validateStorageKey`, `safeParseStoredJson`,
+  `DEFAULT_TOKEN_STORAGE_KEY`, `MAX_STORED_TOKEN_BYTES`.
+- `allowInsecureTransport` config flag (default `false`) — rejects non-HTTPS
+  `baseUrl` outside loopback hosts.
+- [`SECURITY.md`](./SECURITY.md) threat model and integrator checklist.
+- Hardened examples with PKCE redirect flow, signed OAuth session cookies, safe
+  error mapping, and strict input validation ([`examples/`](./examples/)).
+
+### Changed
+
+- Examples now demonstrate authorization code + PKCE as the primary login path;
+  password grant routes are retained for local dev/testing only.
+
+### Migration
+
+1. Remove `createLocalStorageTokenStorage()` — not replaced.
+2. Use HttpOnly cookies for refresh tokens via server routes (see examples).
+3. Implement custom `TokenStorage` with exported validators for platform-specific
+   secure backends (Keychain, Keystore).
+
+### Verified
+
+- `bun run typecheck`
+- `bun run test`
+- `bun run build`
+
+## [0.3.0] - 2026-06-24
+
+### Added
+
+- **Authorization Code + PKCE redirect flow** (`client.authorize`), the headline
+  capability that lets frontends adopt OAuth without re-implementing PKCE/state
+  plumbing per app:
+  - `authorize.createRequest()` — generates CSPRNG `state` + `nonce` + PKCE
+    (`S256` by default) and returns the authorization URL plus the values to
+    persist (`state`, `nonce`, `codeVerifier`, `redirectUri`).
+  - `authorize.parseCallback()` — normalizes a callback URL/query string.
+  - `authorize.handleCallback()` — one call that verifies `state`
+    (constant-time), surfaces server errors, and exchanges the code for tokens.
+- Standalone PKCE/CSRF primitives: `generatePkce`, `generateCodeVerifier`,
+  `deriveCodeChallenge`, `generateState`, `generateNonce`, `randomUrlSafeString`,
+  `timingSafeEqual` — all backed by the platform Web Crypto CSPRNG.
+- `sanitizePostAuthRedirect()` open-redirect guard (rejects protocol-relative,
+  backslash-smuggled, scheme-bearing, and CRLF targets).
+- `oidc.discover()` — fetches and maps `/.well-known/openid-configuration`.
+- Broader public type exports (`AuthorizationUrlOptions`, `AuthorizationRequest`,
+  `CallbackParams`, `HandleCallbackOptions`, `OidcDiscoveryDocument`, endpoint
+  interfaces, `AuthErrorCode`).
+
+### Security
+
+- All anti-forgery/PKCE randomness uses `globalThis.crypto.getRandomValues`,
+  never `Math.random`.
+- `state` is verified with a constant-time comparison (`timingSafeEqual`).
+- PKCE `codeVerifier` is documented as a server-side secret and never appears in
+  the authorization URL.
+
+### Verified
+
+- `bun run typecheck`
+- `bun run test` (includes the RFC 7636 Appendix B S256 vector)
+- `bun run build`
+
+## [0.2.0] - 2026-02-26
+
+### Added
+
+- Framework-agnostic `@tktchurch/auth` SDK core with typed OAuth, OIDC, AuthFlow, sessions, user, and WebAuthn endpoint wrappers.
+- Token lifecycle support with pluggable storage and `fetchWithAuth` one-retry refresh flow.
+- Nuxt module export `@tktchurch/auth/nuxt` with:
+  - `tktAuth` module configuration.
+  - injected `$tktAuth` client via `useTktAuth()`.
+  - server factory `createTktServerAuthClient()`.
+  - cookie helper `useTktRefreshCookieName()`.
+- Next.js and Nuxt3 production examples in `examples/`.
+- Production-gated Nuxt3 integration tests (`tests/nuxt3.production.test.ts`) for login/me/logout patterns.
+- Release metadata and publish hardening:
+  - GitHub Packages publish configuration.
+  - npmjs public publish workflow and scripts.
+  - release workflow and publishing guide.
+
+### Changed
+
+- Default SDK endpoint remains `https://prod-auth.tktchurch.com`.
+- Package version bumped to `0.2.0`.
+- Build output now includes the Nuxt module entry (`./nuxt`).
+- Improved strict TypeScript coverage (no implicit `any` in SDK/Nuxt example handlers).
+
+### Verified
+
+- `bun run typecheck`
+- `bun run test`
+- `bun run build`
+- `bun run test:nuxt3:prod` (passes when target auth server is reachable and seeded credentials are valid)

package/PUBLISHING.md

@@ -0,0 +1,121 @@
+# Publishing Guide (`@tktchurch/auth`)
+
+This package uses a **dual-build** pipeline. The artifact published to each registry differs:
+
+| Registry | Build profile | Contents |
+| --- | --- | --- |
+| **npmjs** (public) | `consumer` | OAuth/OIDC client SDK only — no admin console modules, no `request`/`fetchWithAuth`, no source maps |
+| **GitHub Packages** (private) | `full` | Complete internal SDK (admin CRUD, privacy admin, generic passthrough, source maps) |
+
+Registry selection is command/workflow specific. The repo intentionally does not pin `publishConfig.registry` or a scoped `.npmrc` to avoid cross-registry auth conflicts.
+
+## 1. Prerequisites
+
+- Repository hosted at `tktchurch/auth-sdk-js`.
+- Package scope is `@tktchurch`.
+- You have permission to publish packages in the `tktchurch` organization.
+- npm scope access for `@tktchurch` (or delegated publish rights).
+- A GitHub token with `write:packages` and `repo` scope (for local GitHub publish).
+- An npm token with publish rights (for local npmjs publish).
+- npm trusted publishing configured for this package/repository (for GitHub Actions npmjs publish).
+
+## 2. Local Release Validation
+
+Full internal build (used by `accounts` / `developers` via `file:../auth-sdk-js`):
+
+```bash
+bun run release:check
+```
+
+Consumer build (public npmjs tarball):
+
+```bash
+bun run release:check:consumer
+```
+
+Both run typecheck + tests, then build with the matching profile:
+
+| Script | Build |
+| --- | --- |
+| `bun run build` / `build:full` | `BUILD_PROFILE=full` |
+| `bun run build:consumer` | `BUILD_PROFILE=consumer` |
+
+## 3. Local Publish (Manual)
+
+### 3.1 Publish to GitHub Packages (private, full SDK)
+
+Set auth token:
+
+```bash
+export NODE_AUTH_TOKEN=ghp_xxx
+```
+
+Publish:
+
+```bash
+bun run publish:github
+```
+
+### 3.2 Publish to npmjs (public, consumer SDK)
+
+Set auth token:
+
+```bash
+export NODE_AUTH_TOKEN=npm_xxx
+```
+
+Publish:
+
+```bash
+bun run publish:npmjs
+```
+
+Both publish scripts run the matching `release:check*` pipeline and pass `--ignore-scripts` so `prepublishOnly` does not rebuild with the wrong profile.
+
+## 4. GitHub Actions Publish
+
+Workflow files:
+
+1. `.github/workflows/publish-github-packages.yml` — `build:full` → GitHub Packages
+2. `.github/workflows/publish-npmjs.yml` — `build:consumer` → npmjs
+
+Triggers:
+
+1. Tag push matching `v*` (for example `v0.9.1`)
+2. Manual dispatch
+
+The GitHub Packages workflow installs dependencies, typechecks, tests, builds the **full** bundle, and publishes with `GITHUB_TOKEN`.
+
+The npmjs workflow installs dependencies, typechecks, tests, builds the **consumer** bundle, and publishes using trusted publishing (GitHub OIDC) when configured.
+
+## 5. Tagging and Changelog
+
+1. Update `package.json` version.
+2. Update `CHANGELOG.md`.
+3. Create and push a release tag:
+
+```bash
+git tag v0.9.1
+git push origin v0.9.1
+```
+
+## 6. Required Repository Secrets
+
+1. No npmjs token secret is required for npmjs workflow when OIDC trusted publishing is configured.
+2. GitHub Packages workflow uses `GITHUB_TOKEN` automatically.
+
+## 7. Consumer vs full SDK
+
+**Public npm (`consumer`)** ships:
+
+- `authorize`, `token`, `oidc`, `flow`, `user` (self-service), `sessions`, `webauthn`, `passwordReset`, `mfa`, `maintenance.status`, `oauth` meta
+- PKCE, redirect sanitization, token storage helpers
+- Nuxt module entry
+
+**GitHub Packages (`full`)** additionally ships:
+
+- Admin console namespaces (`clients`, `roles`, `auditLogs`, `dashboard`, …)
+- `request()` and `fetchWithAuth()` passthrough helpers
+- `DEFAULT_BASE_URL` export and full TypeScript admin types
+
+Internal TKTChurch apps should install from GitHub Packages or use `file:../auth-sdk-js` with `bun run build:full`.

package/README.md

@@ -0,0 +1,315 @@
+# `@tktchurch/auth`
+
+Framework-agnostic auth SDK for TKTChurch OAuth/AuthFlow services.
+
+- Default production endpoint: `https://prod-auth.tktchurch.com`
+- Works in browser and Node runtimes (requires `fetch`)
+- Pluggable token storage (`memory` by default)
+- First-class support for AuthFlow endpoints
+
+## Install
+
+```bash
+npm install @tktchurch/auth
+```
+
+## Quick Start
+
+```ts
+import { createAuthClient } from "@tktchurch/auth";
+
+const auth = createAuthClient({
+  clientId: "your_client_id",
+  // Optional:
+  // clientSecret: "your_client_secret",
+  // baseUrl: "https://prod-auth.tktchurch.com",
+});
+
+const tokens = await auth.token.password({
+  username: "user@example.com",
+  password: "your_password",
+  scope: "openid profile email",
+});
+
+console.log(tokens.accessToken);
+```
+
+## Authorization Code + PKCE (redirect flow)
+
+The recommended browser/SSR login flow. The SDK generates PKCE, `state`, and
+`nonce` for you and hands back everything you must persist across the redirect —
+no more hand-rolling crypto per app.
+
+**1. Start the flow** (server route that begins login):
+
+```ts
+import { createAuthClient } from "@tktchurch/auth";
+
+const auth = createAuthClient({ clientId: process.env.TKT_CLIENT_ID! });
+
+const request = await auth.authorize.createRequest({
+  redirectUri: "https://app.example.com/callback",
+  // scope defaults to "openid profile email offline_access"
+});
+
+// Persist these in an HttpOnly cookie / server session, keyed by `state`:
+//   request.state, request.nonce, request.codeVerifier, request.redirectUri
+// Then redirect the user agent:
+//   302 -> request.url
+```
+
+**2. Handle the callback** — one call validates `state` (constant-time),
+surfaces server errors, and exchanges the code for tokens:
+
+```ts
+const tokens = await auth.authorize.handleCallback({
+  callback: requestUrl,            // full callback URL or its query string
+  expectedState: saved.state,      // the state you persisted in step 1
+  codeVerifier: saved.codeVerifier,
+  redirectUri: saved.redirectUri,
+});
+
+// tokens.accessToken / tokens.refreshToken — persist refresh in HttpOnly cookie;
+// keep access token in server memory per request (see examples/).
+```
+
+> Security: the PKCE `codeVerifier` is a secret — keep it server-side (HttpOnly
+> cookie or session store), never in `localStorage`. `state` is verified with a
+> constant-time comparison to defeat CSRF and timing oracles.
+
+### Open-redirect protection
+
+Always sanitize any `next`/`returnTo` value before redirecting after login:
+
+```ts
+import { sanitizePostAuthRedirect } from "@tktchurch/auth";
+
+return Response.redirect(sanitizePostAuthRedirect(next, "/dashboard"));
+// "//evil.com", "https://evil.com", "javascript:…", CRLF → fallback
+```
+
+### Low-level PKCE helpers
+
+If you need the primitives directly:
+
+```ts
+import { generatePkce, generateState, generateNonce, deriveCodeChallenge } from "@tktchurch/auth";
+
+const { codeVerifier, codeChallenge, codeChallengeMethod } = await generatePkce();
+```
+
+### OIDC discovery
+
+```ts
+const meta = await auth.oidc.discover(); // /.well-known/openid-configuration
+console.log(meta.authorizationEndpoint, meta.tokenEndpoint, meta.jwksUri);
+```
+
+## Framework-Agnostic Usage
+
+### Server route (recommended)
+
+Use in-memory storage (the default) and persist refresh tokens in HttpOnly
+cookies. See [`examples/`](./examples/) for full PKCE redirect flows.
+
+```ts
+import { createAuthClient } from "@tktchurch/auth";
+
+const auth = createAuthClient({
+  clientId: process.env.TKT_CLIENT_ID!,
+  clientSecret: process.env.TKT_CLIENT_SECRET!,
+});
+
+export async function GET() {
+  const me = await auth.user.me();
+  return Response.json(me);
+}
+```
+
+> Do **not** store OAuth tokens in `localStorage` or `sessionStorage`. The SDK
+> does not ship a browser persistence adapter — use server-side cookies or a
+> platform secure store (Keychain, Keystore). See [`SECURITY.md`](./SECURITY.md).
+
+## Framework Examples (Best Practices)
+
+Production-oriented examples are available in:
+
+- [`examples/next-app-router`](./examples/next-app-router/README.md)
+- [`examples/nuxt3`](./examples/nuxt3/README.md)
+
+They follow server-first patterns:
+
+1. Authorization code + PKCE redirect flow (primary).
+2. `clientSecret` remains server-only.
+3. Refresh token is stored in `HttpOnly` cookie.
+4. PKCE `codeVerifier` is stored in a signed HttpOnly session cookie.
+5. Refresh token rotation is performed on every refresh call.
+6. Logout revokes refresh token and clears cookies.
+
+## Nuxt Module (`@tktchurch/auth/nuxt`)
+
+Register the module in `nuxt.config.ts`:
+
+```ts
+export default defineNuxtConfig({
+  modules: ["@tktchurch/auth/nuxt"],
+  tktAuth: {
+    baseUrl: process.env.TKT_AUTH_BASE_URL ?? "https://prod-auth.tktchurch.com",
+    clientId: process.env.TKT_CLIENT_ID,
+    clientSecret: process.env.TKT_CLIENT_SECRET,
+    autoRefresh: false,
+    refreshCookieName: "tkt_refresh_token",
+  },
+});
+```
+
+Then use provided imports:
+
+```ts
+const auth = createTktServerAuthClient();
+const appAuth = useTktAuth();
+const refreshCookieName = useTktRefreshCookieName();
+```
+
+## AuthFlow Example
+
+```ts
+const init = await auth.flow.initAuthentication({
+  username: "user@example.com",
+});
+
+let status = await auth.flow.executeStep({
+  sessionId: init.sessionId,
+  stepId: init.currentStep.stepId,
+  credential: {
+    username: "user@example.com",
+    password: "secret",
+  },
+});
+
+while (status.status === "in_progress") {
+  // Render UI for status.nextStep and collect credentials for that step.
+  status = await auth.flow.executeStep({
+    sessionId: status.sessionId,
+    stepId: status.nextStep.stepId,
+    credential: {},
+  });
+}
+
+// status.status === "complete"
+console.log(status.accessToken);
+```
+
+## Token Storage
+
+### Memory (default)
+
+```ts
+import { createAuthClient, createMemoryTokenStorage } from "@tktchurch/auth";
+
+const auth = createAuthClient({
+  clientId: "client_id",
+  storage: createMemoryTokenStorage(),
+});
+```
+
+### Custom `TokenStorage`
+
+For platform-specific secure backends (Keychain, Keystore, encrypted server
+session), implement `TokenStorage` using the exported validators
+(`assertValidAuthTokens`, `parseStoredAuthTokens`, `serializeAuthTokens`).
+See [`SECURITY.md`](./SECURITY.md).
+
+## Error Handling
+
+```ts
+import { AuthError, MFARequiredAuthError } from "@tktchurch/auth";
+
+try {
+  await auth.token.password({
+    username: "user@example.com",
+    password: "secret",
+  });
+} catch (error) {
+  if (error instanceof MFARequiredAuthError) {
+    console.log("MFA required:", error.mfaMethods);
+  } else if (error instanceof AuthError) {
+    console.log(error.code, error.message, error.status);
+  } else {
+    throw error;
+  }
+}
+```
+
+## Authenticated Fetch
+
+`fetchWithAuth` adds the bearer token automatically and retries once on `401` using refresh token when possible.
+
+> **Note:** `fetchWithAuth` and `request()` are available only in the **full** SDK (GitHub Packages / local `file:` build). The public npmjs consumer build omits generic passthrough helpers.
+
+```ts
+const response = await auth.fetchWithAuth("/api/v1/users/me");
+if (!response.ok) {
+  // handle response
+}
+```
+
+## API reference (public consumer build)
+
+The public npmjs package ships OAuth/OIDC client namespaces only. Admin console modules (`clients`, `roles`, `auditLogs`, …) and generic passthrough helpers are available in the **full** SDK from GitHub Packages — see [`CONTEXT.md`](./CONTEXT.md).
+
+| Namespace | Methods | Auth |
+| --- | --- | --- |
+| `token` | `password`, `refresh`, `clientCredentials`, `authorizationCode`, `tokenExchange`, `revoke`, `introspect` | client credentials / stored tokens |
+| `authorize` | `createRequest`, `parseCallback`, `handleCallback`, `consent`, `consentWithCredentials` | public + server session |
+| `oidc` | `userInfo`, `discover`, `jwks` | bearer / public |
+| `oauth` | `publicClient`, `discoverAuthorizationServer` | public |
+| `flow` | `initAuthentication`, `executeStep`, `initRegistration`, `executeRegistrationStep`, `initRecovery`, `executeRecoveryStep`, `getStatus` | public / step session |
+| `user` | `me`, `updateMe`, `changePassword`, `deleteAvatar`, `verifyPhone`, `securityOverview`, `recoveryContacts.*`, `identities.*`, `deleteMe` | bearer |
+| `sessions` | `list`, `current`, `get`, `update`, `revoke`, `revokeAll`, `revokeAllDevices` | bearer |
+| `webauthn` | `registerBegin/Finish`, `authenticateBegin/Finish`, `credentials`, `removeCredential`, `renameCredential`, `setPrimaryCredential` | bearer / public begin |
+| `passwordReset` | `request`, `validate`, `complete` | public |
+| `mfa` | `setup`, `verify`, `devices`, `removeDevice`, `regenerateBackupCodes`, `disable` | bearer |
+| `maintenance` | `status` | public |
+
+Integrators must pass an explicit `baseUrl` in `createAuthClient({ baseUrl, clientId, … })`. The public consumer build does not export `DEFAULT_BASE_URL`.
+
+### Internal admin SDK (GitHub Packages only)
+
+The full build adds `consents`, admin `maintenance.*`, `clients` … `comms`, `privacy`, `user.admin.*`, plus `request()` / `fetchWithAuth()`. Admin methods require a bearer access token with matching backend permissions (`client:read`, `user:write`, `*:*`, etc.). The SDK does not enforce permissions — the OAuth server does.
+
+### Migrating from hand-rolled `oauth.ts`
+
+Replace direct `fetch` calls with namespaced SDK methods:
+
+```ts
+// Before
+await fetch(`${baseUrl}/oauth/token`, { method: "POST", body });
+
+// After
+const tokens = await auth.token.authorizationCode({ code, redirectUri, codeVerifier });
+```
+
+For admin console CRUD (`/api/v1/clients`, etc.), use the **full** SDK from GitHub Packages — see [`CONTEXT.md`](./CONTEXT.md).
+
+Inject internal URL rewriting via `createAuthClient({ fetch })` — same pattern as
+`accounts` / `developers` `oauth-fetch.ts`.
+
+## Release and Publish
+
+- Changelog: [`CHANGELOG.md`](./CHANGELOG.md)
+- Publishing guide: [`PUBLISHING.md`](./PUBLISHING.md)
+
+GitHub Packages (private, `tktchurch` scope) is configured via:
+
+- Script: `bun run publish:github`
+- Workflow: [`.github/workflows/publish-github-packages.yml`](./.github/workflows/publish-github-packages.yml)
+- Auth token: `NODE_AUTH_TOKEN` (`GITHUB_TOKEN` in workflow)
+
+npmjs (public) publishing ships the **consumer** build only:
+
+- Script: `bun run publish:npmjs` (runs `release:check:consumer`)
+- Workflow: [`.github/workflows/publish-npmjs.yml`](./.github/workflows/publish-npmjs.yml)
+- Auth: npm trusted publishing (OIDC, no `NPM_TOKEN` secret) or local `NODE_AUTH_TOKEN`
+
+GitHub Packages ships the **full** internal SDK. See [`PUBLISHING.md`](./PUBLISHING.md) for the dual-build matrix.