@sylphx/contract 0.2.0

package/dist/schemas/auth.js

@@ -0,0 +1,815 @@
+/**
+ * Auth — BaaS plane primitives. Matches `@sylphx/sdk` `auth.ts` public
+ * surface (sign-in, sign-up, session, 2FA).
+ *
+ * Two layers coexist here (ADR-084):
+ *
+ * 1. **Lean primitives** (`SignInInput`, `SignUpInput`, `SessionResult`) —
+ *    the minimal shape a generic OAuth/OIDC consumer needs. Stable;
+ *    brand-safe; closed.
+ *
+ * 2. **SDK wire shapes** (`LoginRequest`, `LoginResponse`, `RegisterRequest`,
+ *    `RegisterResponse`, `AuthTokensResponse`, `TwoFactorVerifyRequest`,
+ *    `UserFullProfile`) — richer request/response envelopes the REST API
+ *    actually returns. Mirror the OpenAPI schema previously consumed from
+ *    `@sylphx/sdk/src/generated/api.d.ts`. Declared as plain `Struct`s with
+ *    unbranded `Schema.String` ids so the SDK (which hands ids straight to
+ *    URL builders, cookies, etc.) can accept them without casts.
+ */
+import { Schema } from 'effect';
+import { UserId } from './ids.js';
+/** Tokens issued by `/auth/login` / `/auth/token`. */
+export const AuthTokens = Schema.Struct({
+    accessToken: Schema.String,
+    refreshToken: Schema.optional(Schema.String),
+    tokenType: Schema.optional(Schema.String),
+    expiresIn: Schema.optional(Schema.Number),
+});
+export const SessionUser = Schema.Struct({
+    id: UserId,
+    email: Schema.String,
+    name: Schema.NullOr(Schema.String),
+    image: Schema.NullOr(Schema.String),
+    emailVerified: Schema.Boolean,
+});
+export const SignInInput = Schema.Struct({
+    email: Schema.String,
+    password: Schema.String,
+});
+/** Success path issues tokens; 2FA path redirects via `requiresTwoFactor`. */
+export const SignInResult = Schema.Struct({
+    requiresTwoFactor: Schema.optional(Schema.Boolean),
+    userId: Schema.optional(UserId),
+    accessToken: Schema.optional(Schema.String),
+    refreshToken: Schema.optional(Schema.String),
+    tokenType: Schema.optional(Schema.String),
+    expiresIn: Schema.optional(Schema.Number),
+});
+export const SignUpInput = Schema.Struct({
+    email: Schema.String,
+    password: Schema.String,
+    name: Schema.optional(Schema.String),
+});
+export const SignUpResult = Schema.Struct({
+    userId: UserId,
+    email: Schema.String,
+    emailVerified: Schema.Boolean,
+});
+export const SessionResult = Schema.Struct({
+    user: Schema.NullOr(SessionUser),
+});
+// ── SDK wire shapes ────────────────────────────────────────────────────────
+//
+// These mirror the OpenAPI component schemas the REST API emits. Ids are
+// plain strings (not `UserId`) because SDK callers pass them through to
+// `URL`, cookies, and storage primitives that don't understand branded
+// types — see `@sylphx/sdk/src/auth.ts` notes on the contract/SDK id-brand
+// divide.
+/** Minimal user returned inside login/token/register envelopes. */
+export const AuthUser = Schema.Struct({
+    id: Schema.String,
+    email: Schema.String,
+    name: Schema.NullOr(Schema.String),
+    image: Schema.optional(Schema.NullOr(Schema.String)),
+    emailVerified: Schema.optional(Schema.Boolean),
+    role: Schema.optional(Schema.String),
+    createdAt: Schema.optional(Schema.String),
+});
+/** `POST /auth/login` request body. */
+export const LoginRequest = Schema.Struct({
+    email: Schema.String,
+    password: Schema.String,
+});
+/**
+ * `POST /auth/login` response — discriminated on `requiresTwoFactor`.
+ *
+ * - `true`: caller must finish the 2FA flow via `POST /auth/verify-2fa`
+ *   using the returned `userId`.
+ * - `false` / absent: tokens + user profile are returned directly.
+ */
+export const LoginResponse = Schema.Union(Schema.Struct({
+    requiresTwoFactor: Schema.Literal(true),
+    userId: Schema.String,
+    email: Schema.optional(Schema.String),
+}), Schema.Struct({
+    requiresTwoFactor: Schema.optional(Schema.Literal(false)),
+    accessToken: Schema.String,
+    refreshToken: Schema.optional(Schema.String),
+    expiresIn: Schema.optional(Schema.Number),
+    user: Schema.optional(AuthUser),
+}));
+/**
+ * `POST /auth/register` request body — a superset of `SignUpInput` that
+ * accepts caller metadata and an optional invitation token.
+ */
+export const RegisterRequest = Schema.Struct({
+    email: Schema.String,
+    password: Schema.String,
+    name: Schema.optional(Schema.String),
+    metadata: Schema.optional(Schema.Record({ key: Schema.String, value: Schema.Unknown })),
+    invitationToken: Schema.optional(Schema.String),
+});
+/** `POST /auth/register` response — email-verification envelope. */
+export const RegisterResponse = Schema.Struct({
+    requiresVerification: Schema.optional(Schema.Boolean),
+    message: Schema.optional(Schema.String),
+    user: Schema.Struct({
+        id: Schema.String,
+        email: Schema.String,
+        name: Schema.NullOr(Schema.String),
+    }),
+});
+/**
+ * Token-issuing response shared by `/auth/token`, `/auth/verify-2fa`,
+ * `/auth/switch-org`. `user` is surfaced for SDK convenience (hydrating the
+ * local session immediately after issuance).
+ */
+export const AuthTokensResponse = Schema.Struct({
+    accessToken: Schema.String,
+    refreshToken: Schema.String,
+    expiresIn: Schema.optional(Schema.Number),
+    tokenType: Schema.optional(Schema.String),
+    user: Schema.optional(AuthUser),
+});
+/**
+ * `POST /auth/verify-2fa` request body.
+ *
+ * The OpenAPI spec lists `code` only (post-login flow where the server has
+ * the user bound to the challenge session). The SDK uses an extended shape
+ * including `userId` for the stateless public flow — both are accepted.
+ */
+export const TwoFactorVerifyRequest = Schema.Struct({
+    userId: Schema.optional(Schema.String),
+    code: Schema.String,
+});
+/** `GET /auth/me` response — full profile with verification + timestamps. */
+export const UserFullProfile = Schema.Struct({
+    id: Schema.String,
+    email: Schema.String,
+    name: Schema.NullOr(Schema.String),
+    image: Schema.NullOr(Schema.String),
+    emailVerified: Schema.optional(Schema.Boolean),
+    createdAt: Schema.optional(Schema.String),
+});
+// ─── OAuth Device Flow (RFC 8628) ──────────────────────────────────────────
+//
+// The RFC-8628 device authorization grant is the *client-agnostic*
+// bootstrap surface BaaS issues to any headless client (CLI, TV apps,
+// IoT). ADR-089 Phase 2a hoists the CLI device flow out of the
+// Platform-layer bypass and into the BaaS `/v1/auth/device/*` surface
+// where every consumer — customer and Platform-as-customer alike —
+// speaks the same RFC-shaped protocol.
+//
+// Phase 5.1 will layer RFC 6749 + 7662 + 8414 on top (PKCE, token,
+// revoke, introspect, metadata); Phase 2a ships the four device-flow
+// endpoints that the CLI requires to dogfood.
+/**
+ * `POST /auth/device` request body — initiate a device authorization
+ * grant per RFC 8628 §3.1.
+ */
+export const DeviceInitRequest = Schema.Struct({
+    /**
+     * Client identifier — must match a well-known client registered on
+     * the BaaS plane. Phase 2a hard-codes `sylphx-cli` as the only
+     * allow-listed value; Phase 5.1 replaces the allow-list with the
+     * `oauth_clients` DB registry (ADR-086).
+     */
+    client_id: Schema.String,
+    /**
+     * Space- or array-delimited OAuth scopes the client is requesting.
+     * Phase 2a accepts any scope shape; Phase 5.1 will validate against
+     * the client's registered scope set.
+     */
+    scope: Schema.optional(Schema.Array(Schema.String)),
+});
+/**
+ * `POST /auth/device` response — grant issued per RFC 8628 §3.2.
+ *
+ * `device_code` is the CLI's private reference (opaque bearer);
+ * `user_code` is the short human-readable code the user enters on the
+ * verification page.
+ */
+export const DeviceInitResponse = Schema.Struct({
+    device_code: Schema.String,
+    user_code: Schema.String,
+    verification_uri: Schema.String,
+    verification_uri_complete: Schema.String,
+    expires_in: Schema.Number,
+    interval: Schema.Number,
+});
+/**
+ * `GET /auth/device/poll?device_code=…` response.
+ *
+ * Mirrors the RFC 8628 §3.5 polling token-endpoint response but in a
+ * single envelope so the SDK can discriminate on `status` without
+ * needing a second round-trip to the RFC 6749 token endpoint. Phase
+ * 5.1 will add a strict RFC 6749 `/oauth/token` endpoint that callers
+ * MAY hit instead when they prefer the canonical shape.
+ */
+export const DevicePollResponse = Schema.Union(Schema.Struct({ status: Schema.Literal('pending') }), Schema.Struct({
+    status: Schema.Literal('approved'),
+    access_token: Schema.String,
+    refresh_token: Schema.String,
+    token_type: Schema.Literal('Bearer'),
+    expires_in: Schema.Number,
+    refresh_expires_at: Schema.String,
+}), Schema.Struct({ status: Schema.Literal('denied') }), Schema.Struct({ status: Schema.Literal('expired') }));
+/**
+ * `POST /auth/device/approve` request body — browser leg, user-facing.
+ *
+ * Called from the Console's verification page after the user clicks
+ * Authorize. Cookie-session auth identifies the approving user;
+ * `user_code` is the short public code the user typed / confirmed on
+ * the verification page.
+ */
+export const DeviceApproveRequest = Schema.Struct({
+    user_code: Schema.String,
+});
+/**
+ * `POST /auth/device/approve` response — confirmation envelope.
+ * The CLI picks up the tokens on its next `/auth/device/poll` call.
+ */
+export const DeviceApproveResponse = Schema.Struct({
+    success: Schema.Literal(true),
+});
+/**
+ * `POST /auth/device/deny` request body — same shape as approve.
+ */
+export const DeviceDenyRequest = Schema.Struct({
+    user_code: Schema.String,
+});
+/**
+ * `POST /auth/device/deny` response.
+ */
+export const DeviceDenyResponse = Schema.Struct({
+    success: Schema.Literal(true),
+});
+// ─── OAuth /oauth/token (ADR-089 Phase 5.1b + 5.1c) ───────────────────────────
+//
+// RFC 6749 §3.2 token endpoint — the unified mint surface for every
+// Platform-issued access/refresh bearer. Phase 5.1b shipped the
+// authorization_code + refresh_token grants; Phase 5.1c extends the
+// dispatcher with device_code (RFC 8628 §3.4) + client_credentials
+// (RFC 6749 §4.4). The contract schemas here model the wire shape but the
+// runtime still parses bodies as `Record<string, string>` for forward
+// compatibility — unknown grant-type fields MUST not fail the dispatcher
+// before the client auth check runs.
+/**
+ * `authorization_code` grant body — RFC 6749 §4.1.3 + RFC 7636.
+ */
+export const OAuthTokenAuthorizationCodeRequest = Schema.Struct({
+    grant_type: Schema.Literal('authorization_code'),
+    code: Schema.String,
+    redirect_uri: Schema.String,
+    client_id: Schema.String,
+    client_secret: Schema.optional(Schema.String),
+    code_verifier: Schema.String,
+});
+/**
+ * `refresh_token` grant body — RFC 6749 §6. Rotation is mandatory on the
+ * server side; clients simply present their current refresh_token.
+ */
+export const OAuthTokenRefreshRequest = Schema.Struct({
+    grant_type: Schema.Literal('refresh_token'),
+    refresh_token: Schema.String,
+    client_id: Schema.String,
+    client_secret: Schema.optional(Schema.String),
+    scope: Schema.optional(Schema.String),
+});
+/**
+ * `device_code` grant body — RFC 8628 §3.4. Client auth is registry-driven;
+ * public clients present `client_id` only, confidential clients add
+ * `client_secret`.
+ */
+export const OAuthTokenDeviceCodeRequest = Schema.Struct({
+    grant_type: Schema.Literal('urn:ietf:params:oauth:grant-type:device_code'),
+    device_code: Schema.String,
+    client_id: Schema.String,
+    client_secret: Schema.optional(Schema.String),
+});
+/**
+ * `client_credentials` grant body — RFC 6749 §4.4. Confidential clients
+ * only; `client_secret` is mandatory.
+ */
+export const OAuthTokenClientCredentialsRequest = Schema.Struct({
+    grant_type: Schema.Literal('client_credentials'),
+    client_id: Schema.String,
+    client_secret: Schema.String,
+    scope: Schema.optional(Schema.String),
+});
+/**
+ * Union of every token-endpoint request shape. Discriminated by
+ * `grant_type` — new grants join the union, never replace an existing
+ * variant. Rejected grant types return an RFC 6749 §5.2 error envelope
+ * with `error='unsupported_grant_type'`.
+ */
+export const OAuthTokenRequest = Schema.Union(OAuthTokenAuthorizationCodeRequest, OAuthTokenRefreshRequest, OAuthTokenDeviceCodeRequest, OAuthTokenClientCredentialsRequest);
+/**
+ * Successful `/oauth/token` response carrying access + refresh token pair.
+ * Used by `authorization_code`, `refresh_token`, and `device_code` grants.
+ */
+export const OAuthTokenResponse = Schema.Struct({
+    access_token: Schema.String,
+    token_type: Schema.Literal('Bearer'),
+    expires_in: Schema.Number,
+    refresh_token: Schema.String,
+    scope: Schema.String,
+});
+/**
+ * `client_credentials` success response — RFC 6749 §4.4.3 forbids refresh
+ * tokens on this grant, so the envelope is deliberately narrower.
+ */
+export const OAuthClientCredentialsResponse = Schema.Struct({
+    access_token: Schema.String,
+    token_type: Schema.Literal('Bearer'),
+    expires_in: Schema.Number,
+    scope: Schema.String,
+});
+/**
+ * RFC 6749 §5.2 error codes + RFC 8628 §3.5 polling codes. One closed
+ * enumeration — SDK callers pattern-match on this value to choose the
+ * next action (retry / abort / re-auth).
+ */
+export const OAuthTokenErrorCode = Schema.Literal(
+// RFC 6749 §5.2
+'invalid_request', 'invalid_client', 'invalid_grant', 'unauthorized_client', 'unsupported_grant_type', 'invalid_scope', 
+// RFC 8628 §3.5 — device_code grant only.
+'authorization_pending', 'slow_down', 'access_denied', 'expired_token');
+/**
+ * RFC 6749 §5.2 error envelope. Surfaced with HTTP 400 (or 401 when a
+ * Basic auth header was presented with bad credentials).
+ */
+export const OAuthTokenErrorResponse = Schema.Struct({
+    error: OAuthTokenErrorCode,
+    error_description: Schema.optional(Schema.String),
+    error_uri: Schema.optional(Schema.String),
+});
+// ─── OAuth /oauth/revoke (RFC 7009, ADR-089 Phase 5.1d) ────────────────────
+//
+// Revocation is deliberately uniform across access + refresh tokens on the
+// wire — the server disambiguates by `token_type_hint` OR by probing both
+// stores. The response is always 200 with an empty body per §2.2; error
+// envelopes (`OAuthTokenErrorResponse`) apply only on client-auth /
+// malformed-request paths.
+/**
+ * `/oauth/revoke` request body — RFC 7009 §2.1.
+ */
+export const OAuthRevokeRequest = Schema.Struct({
+    token: Schema.String,
+    token_type_hint: Schema.optional(Schema.Literal('access_token', 'refresh_token')),
+    client_id: Schema.String,
+    client_secret: Schema.optional(Schema.String),
+});
+/**
+ * `/oauth/revoke` success response — per §2.2 an empty body. Modelled as
+ * an empty struct so the SDK has a typed `void`-equivalent to await.
+ */
+export const OAuthRevokeResponse = Schema.Struct({});
+// ─── OAuth /oauth/introspect (RFC 7662, ADR-089 Phase 5.1d) ────────────────
+//
+// Introspection returns either the full active-token envelope OR the
+// `{ active: false }` sentinel. RFC 7662 §2.2 requires `active` to be
+// present on every response; all other fields are optional. The schema
+// reflects that — every claim is `optional` so a strict parser cannot
+// reject the inactive sentinel.
+/**
+ * `/oauth/introspect` request body — RFC 7662 §2.1. Same auth model as
+ * `/oauth/revoke` (client_id + optional client_secret, or Basic header).
+ */
+export const OAuthIntrospectRequest = Schema.Struct({
+    token: Schema.String,
+    token_type_hint: Schema.optional(Schema.Literal('access_token', 'refresh_token')),
+    client_id: Schema.String,
+    client_secret: Schema.optional(Schema.String),
+});
+/**
+ * `/oauth/introspect` response — RFC 7662 §2.2. Only `active` is required.
+ * Inactive responses carry ONLY `{ active: false }` per §4; populated
+ * responses echo the token's claims (scope, client_id, username, etc.).
+ */
+export const OAuthIntrospectResponse = Schema.Struct({
+    active: Schema.Boolean,
+    scope: Schema.optional(Schema.String),
+    client_id: Schema.optional(Schema.String),
+    username: Schema.optional(Schema.String),
+    token_type: Schema.optional(Schema.Literal('Bearer')),
+    exp: Schema.optional(Schema.Number),
+    iat: Schema.optional(Schema.Number),
+    nbf: Schema.optional(Schema.Number),
+    sub: Schema.optional(Schema.String),
+    aud: Schema.optional(Schema.Union(Schema.String, Schema.Array(Schema.String))),
+    iss: Schema.optional(Schema.String),
+    jti: Schema.optional(Schema.String),
+});
+// ─── Platform Sessions (ADR-089 Phase 2b) ──────────────────────────────────
+//
+// Session management for the Platform plane (Console / CLI operators).
+// These schemas back the `/auth/platform-sessions/*` endpoints in
+// `apps/runtime` that Phase 2b migrates off the Platform bypass (previously
+// served by `apps/api/.../security/sessions.ts` + `user.ts` imports of
+// `@sylphx/core/features/auth/lib/sessions`).
+//
+// Shapes deliberately mirror the Platform-side `SecuritySession` /
+// `GetSessionsResult` / `RevokeOtherSessionsResult` etc. in
+// `packages/contract/src/schemas/security.ts` so the SDK swap is a
+// zero-diff pass-through on the Platform side.
+/**
+ * A single platform-plane session row as surfaced to the client.
+ *
+ * `id` is the prefixed TypeID (`sess_*`) — the BaaS route encodes the
+ * underlying UUID on the way out. Consumers must pass this back
+ * verbatim on the revoke/rename endpoints; the BaaS side accepts both
+ * forms via `parseIdOrError` but the canonical wire representation is
+ * prefixed.
+ */
+export const PlatformSession = Schema.Struct({
+    id: Schema.String,
+    name: Schema.NullOr(Schema.String),
+    ipAddress: Schema.NullOr(Schema.String),
+    userAgent: Schema.NullOr(Schema.String),
+    createdAt: Schema.String,
+    lastActiveAt: Schema.NullOr(Schema.String),
+    isCurrent: Schema.Boolean,
+});
+/**
+ * `GET /auth/platform-sessions` — list envelope.
+ *
+ * Ordering: most-recently-active first (descending `lastActiveAt`).
+ * Matches the pre-existing Platform `GetSessionsResult` shape so the
+ * migration is a drop-in on the caller side.
+ */
+export const PlatformSessionsListResponse = Schema.Struct({
+    sessions: Schema.Array(PlatformSession),
+});
+/**
+ * `POST /auth/platform-sessions/revoke` — revoke one session.
+ *
+ * `sessionId` accepts either the prefixed TypeID (`sess_*`, preferred)
+ * or the raw UUID — the BaaS side normalises via `parseIdOrError`.
+ */
+export const PlatformSessionRevokeRequest = Schema.Struct({
+    sessionId: Schema.String,
+});
+export const PlatformSessionRevokeResponse = Schema.Struct({
+    success: Schema.Literal(true),
+});
+/**
+ * `POST /auth/platform-sessions/revoke-other` — revoke every session
+ * except the one presenting the current access token.
+ *
+ * When the token carries no `sid` claim (pure-Bearer CLI/CI flows),
+ * every session for the user is revoked — equivalent to `revoke-all`.
+ */
+export const PlatformSessionRevokeOtherResponse = Schema.Struct({
+    revokedCount: Schema.Number,
+});
+/**
+ * `POST /auth/platform-sessions/revoke-all` — revoke every session for
+ * the user, including the caller's own. Used by "sign me out
+ * everywhere" after a password change or a compromise scare.
+ */
+export const PlatformSessionRevokeAllResponse = Schema.Struct({
+    success: Schema.Literal(true),
+    count: Schema.Number,
+});
+/**
+ * `POST /auth/platform-sessions/rename` — update the user-visible
+ * device label on a session row.
+ */
+export const PlatformSessionRenameRequest = Schema.Struct({
+    sessionId: Schema.String,
+    name: Schema.String,
+});
+export const PlatformSessionRenameResponse = Schema.Struct({
+    success: Schema.Literal(true),
+});
+// ─── Platform Password (ADR-089 Phase 2c) ──────────────────────────────────
+//
+// Password management for the Platform plane (Console / CLI operators).
+// These schemas back the `/auth/platform-password/*` endpoints in
+// `apps/runtime` that Phase 2c migrates off the Platform bypass (previously
+// served by `apps/api/.../security/password.ts` + `user.ts` imports of
+// `@sylphx/core/features/auth/lib/password`).
+//
+// Shapes deliberately mirror the Platform-side `PasswordStatusResult` /
+// `SetPasswordInput` / `ChangePasswordInput` in the contract's
+// `schemas/security.ts` + `schemas/user.ts` so the SDK swap is a
+// zero-diff pass-through on the Platform side. All primitive-hash work
+// (bcrypt/argon2/scrypt) lives inside the BaaS route — Platform callers
+// never touch the primitives directly (ADR-089 §5 S1–S4).
+/**
+ * `GET /auth/platform-password/status` — whether the authenticated user
+ * has a password set. OAuth-only users return `{ hasPassword: false }`.
+ */
+export const PlatformPasswordStatusResponse = Schema.Struct({
+    hasPassword: Schema.Boolean,
+});
+/**
+ * `POST /auth/platform-password/set` — initial password for users that
+ * don't have one (signed up via OAuth, never set a local password).
+ *
+ * BaaS enforces the 8-char minimum and the have-i-been-pwned breach check
+ * server-side; Platform callers just forward the plaintext.
+ */
+export const PlatformPasswordSetRequest = Schema.Struct({
+    password: Schema.String,
+});
+export const PlatformPasswordSetResponse = Schema.Struct({
+    success: Schema.Literal(true),
+});
+/**
+ * `POST /auth/platform-password/change` — change an existing password.
+ *
+ * `currentPassword` verification happens server-side via
+ * `verifyPasswordEffect`; a mismatch returns 401 UNAUTHORIZED. Users
+ * that are OAuth-only (no `passwordHash`) receive a 400 so the UI can
+ * redirect them to `set`.
+ */
+export const PlatformPasswordChangeRequest = Schema.Struct({
+    currentPassword: Schema.String,
+    newPassword: Schema.String,
+});
+export const PlatformPasswordChangeResponse = Schema.Struct({
+    success: Schema.Literal(true),
+});
+// ─── Platform User Data (ADR-089 Phase 2d) ─────────────────────────────────
+//
+// GDPR operations for the Platform plane (Console / CLI operators).
+// These schemas back the `/auth/platform-user/*` endpoints in
+// `apps/runtime` that Phase 2d migrates off the Platform bypass
+// (previously served by `apps/api/.../user.ts` reaching directly into
+// `@sylphx/core/lib/auth/index` for `exportUserData` + `deleteUserData`).
+//
+// Shapes deliberately mirror `UserDataExport` / `DeleteAccountResult` in
+// `schemas/user.ts` so the SDK swap is a zero-diff pass-through on the
+// Platform side. All cascading erasure work (per-project BaaS DBs,
+// Stripe cleanup, S3 blob deletion, audit anonymisation) lives inside
+// the BaaS route — Platform callers never touch the underlying stores
+// directly, per ADR-089 Principle 2.
+/**
+ * `GET /auth/platform-user/export` — GDPR data-portability envelope.
+ *
+ * Deliberately permissive — the export contains per-project data that
+ * varies by customer provisioning (storage files, project memberships,
+ * subscription rows). Platform callers pass the whole record through
+ * to the user verbatim; the Console renders it as a JSON download.
+ */
+export const AuthUserExportResponse = Schema.Record({
+    key: Schema.String,
+    value: Schema.Unknown,
+});
+/**
+ * `DELETE /auth/platform-user/account` — GDPR right-to-erasure request.
+ *
+ * `reason` is optional operator context (`user_request` / `admin_action`
+ * / `account_violation`); the BaaS route defaults to `user_request`.
+ * Production hardening (WebAuthn step-up challenge) lands in Phase 5.11 —
+ * see the handler TODO.
+ */
+export const AuthUserDeleteRequest = Schema.Struct({
+    reason: Schema.optional(Schema.String),
+});
+/**
+ * `DELETE /auth/platform-user/account` response.
+ *
+ * `deletedData` is the string list of resource kinds actually erased
+ * (sessions, oauthAccounts, projectUsers, storageFiles, …). Mirrors the
+ * `UserDeletionResult.deletedData` surface from the core helper but
+ * flattened to a string array — the per-kind counts are audit-log
+ * payload only.
+ */
+export const AuthUserDeleteResponse = Schema.Struct({
+    success: Schema.Boolean,
+    deletedData: Schema.Array(Schema.String),
+});
+// ─── Platform Audit Query (ADR-089 Phase 5.3b) ─────────────────────────────
+//
+// Scope-filtered reader for the tamper-evident audit-log chain introduced
+// by Phase 5.3 foundation. Backs the `/audit/query` endpoint in
+// `apps/runtime/src/server/runtime/routes/audit.ts` (renamed out of
+// `/auth/platform-audit/*` by Phase Σ1 SoC rename).
+//
+// Scope enforcement (server-side — `audit` handler in runtime):
+//   - `super_admin` / `admin`  → all scopes, all rows.
+//   - project admin           → `project-ops` + `app-events` for projects
+//                                 they admin (org-level role check).
+//   - regular user            → `project-ops` for projects they're a member
+//                                 of, OR their own `app-events`.
+//   - scope escalation        → 403 `audit_scope_forbidden`.
+//
+// Cursor is opaque, HMAC-signed: base64({ lastTs, lastId }) + sig. Clients
+// MUST treat it as a black box — the shape is NOT a wire contract and can
+// change without a version bump.
+/** Scope taxonomy — matches `audit_logs.scope` CHECK on the DB side. */
+export const AuditScopeLiteral = Schema.Literal('platform-ops', 'project-ops', 'app-events');
+/**
+ * `GET /audit/query` — filter envelope. All fields optional
+ * except `limit` (default 100, max 500). `from` / `to` are ISO-8601 UTC;
+ * `cursor` paginates; `scope` narrows to one plane (caller role must
+ * include it — see scope enforcement notes above).
+ */
+export const PlatformAuditQueryRequest = Schema.Struct({
+    scope: Schema.optional(AuditScopeLiteral),
+    actor: Schema.optional(Schema.String),
+    resourceType: Schema.optional(Schema.String),
+    resourceId: Schema.optional(Schema.String),
+    action: Schema.optional(Schema.String),
+    from: Schema.optional(Schema.String),
+    to: Schema.optional(Schema.String),
+    cursor: Schema.optional(Schema.String),
+    limit: Schema.optional(Schema.Number),
+});
+/** One audit row as surfaced to the query client. Hashes are hex-encoded. */
+export const PlatformAuditEvent = Schema.Struct({
+    id: Schema.String,
+    ts: Schema.String,
+    scope: AuditScopeLiteral,
+    actor: Schema.NullOr(Schema.String),
+    user: Schema.NullOr(Schema.String),
+    orgId: Schema.NullOr(Schema.String),
+    projectId: Schema.NullOr(Schema.String),
+    resourceType: Schema.String,
+    resourceId: Schema.NullOr(Schema.String),
+    action: Schema.String,
+    metadata: Schema.NullOr(Schema.Record({ key: Schema.String, value: Schema.Unknown })),
+    prevHashHex: Schema.NullOr(Schema.String),
+    rowHashHex: Schema.NullOr(Schema.String),
+});
+/**
+ * Response envelope — paginated events + chain-verification flag.
+ *
+ * `chainVerified` is `true` when every returned row's `prev_hash` equals
+ * the preceding row's `row_hash` (rows returned in chain order). It MAY
+ * be `false` when a range query skips a row (rare; not corruption) —
+ * the field is advisory for the client, the ground-truth verifier is
+ * `scripts/check-audit-hash-chain.ts --nightly`.
+ */
+export const PlatformAuditQueryResponse = Schema.Struct({
+    events: Schema.Array(PlatformAuditEvent),
+    nextCursor: Schema.NullOr(Schema.String),
+    chainVerified: Schema.Boolean,
+});
+// ─── Platform Rate-Limit API (ADR-089 Phase 5.2) ───────────────────────────
+//
+// BaaS surface that lets operators inspect live rate-limit counter state and
+// manage per-(scope, scope_id, namespace) strategy overrides without a code
+// deploy. Enforcement reads the override table through the resolver with a
+// 60s in-process cache; upserts/deletes invalidate the cache in-band and
+// the next read sees the new config. Missing overrides fall through to the
+// hard-coded `RateLimitPresets` defaults in `@sylphx/core`.
+//
+// Scope enforcement (server-side — `authPlatformRateLimits` handler):
+//   - super_admin / admin → all scopes.
+//   - project admin       → `project` + their project_id only.
+//   - regular user        → `user` + their own user id only.
+//   - scope escalation    → 403 `rate_limit_scope_forbidden`.
+/** Scope taxonomy — mirrors `RATE_LIMIT_SCOPES` in the Drizzle schema. */
+export const RateLimitScopeLiteral = Schema.Literal('global', 'project', 'user');
+/** Strategy taxonomy — mirrors `RATE_LIMIT_STRATEGIES`. */
+export const RateLimitStrategyLiteral = Schema.Literal('token-bucket', 'sliding-window', 'fixed-window');
+const NamespaceString = Schema.String.pipe(Schema.pattern(/^[a-zA-Z][a-zA-Z0-9_-]{0,63}$/));
+export const PlatformRateLimitStatusRequest = Schema.Struct({
+    scope: Schema.optional(RateLimitScopeLiteral),
+    scope_id: Schema.optional(Schema.String),
+    namespace: Schema.optional(NamespaceString),
+});
+export const PlatformRateLimitStatusRow = Schema.Struct({
+    namespace: Schema.String,
+    scope: RateLimitScopeLiteral,
+    scopeId: Schema.NullOr(Schema.String),
+    strategy: RateLimitStrategyLiteral,
+    limit: Schema.Number,
+    windowSeconds: Schema.Number,
+    burst: Schema.NullOr(Schema.Number),
+    source: Schema.Literal('default', 'global', 'project', 'user'),
+});
+export const PlatformRateLimitStatusResponse = Schema.Struct({
+    rows: Schema.Array(PlatformRateLimitStatusRow),
+});
+export const PlatformRateLimitStrategiesListRequest = Schema.Struct({
+    scope: Schema.optional(RateLimitScopeLiteral),
+    scope_id: Schema.optional(Schema.String),
+});
+export const PlatformRateLimitStrategyRow = Schema.Struct({
+    id: Schema.String,
+    scope: RateLimitScopeLiteral,
+    scopeId: Schema.NullOr(Schema.String),
+    namespace: Schema.String,
+    strategy: RateLimitStrategyLiteral,
+    limitCount: Schema.Number,
+    windowSeconds: Schema.Number,
+    burstCount: Schema.NullOr(Schema.Number),
+    updatedAt: Schema.String,
+    updatedBy: Schema.NullOr(Schema.String),
+});
+export const PlatformRateLimitStrategiesListResponse = Schema.Struct({
+    strategies: Schema.Array(PlatformRateLimitStrategyRow),
+});
+export const PlatformRateLimitNamespaceParams = Schema.Struct({
+    namespace: NamespaceString,
+});
+export const PlatformRateLimitStrategyUpsertRequest = Schema.Struct({
+    scope: RateLimitScopeLiteral,
+    scope_id: Schema.optional(Schema.String),
+    strategy: RateLimitStrategyLiteral,
+    limit: Schema.Number,
+    windowSeconds: Schema.Number,
+    burst: Schema.optional(Schema.NullOr(Schema.Number)),
+});
+export const PlatformRateLimitStrategyUpsertResponse = Schema.Struct({
+    strategy: PlatformRateLimitStrategyRow,
+});
+export const PlatformRateLimitStrategyDeleteRequest = Schema.Struct({
+    scope: RateLimitScopeLiteral,
+    scope_id: Schema.optional(Schema.String),
+});
+export const PlatformRateLimitStrategyDeleteResponse = Schema.Struct({
+    deleted: Schema.Boolean,
+});
+// ============================================================================
+// Passkey-Primary Signup — ADR-089 Phase 5.11 / P14 + S26
+// ============================================================================
+/**
+ * Passkey signup-challenge request. `orgId` binds the ceremony to an org
+ * for policy enforcement (device-bound + AAGUID allow-list). Omit for
+ * personal signups.
+ */
+export const PasskeySignupChallengeRequest = Schema.Struct({
+    email: Schema.String,
+    displayName: Schema.optional(Schema.String),
+    orgId: Schema.optional(Schema.String),
+});
+/**
+ * WebAuthn registration options + platform-issued `userHandle`. Caller
+ * feeds these to `navigator.credentials.create({ publicKey: options })`
+ * and echoes `userHandle` back to /signup-verify.
+ */
+export const PasskeySignupChallengeResponse = Schema.Struct({
+    challenge: Schema.String,
+    rp: Schema.Struct({
+        name: Schema.String,
+        id: Schema.optional(Schema.String),
+    }),
+    user: Schema.Struct({
+        id: Schema.String,
+        name: Schema.String,
+        displayName: Schema.String,
+    }),
+    pubKeyCredParams: Schema.Array(Schema.Struct({ type: Schema.Literal('public-key'), alg: Schema.Number })),
+    timeout: Schema.optional(Schema.Number),
+    attestation: Schema.optional(Schema.String),
+    authenticatorSelection: Schema.optional(Schema.Struct({
+        authenticatorAttachment: Schema.optional(Schema.Literal('platform', 'cross-platform')),
+        residentKey: Schema.optional(Schema.Literal('discouraged', 'preferred', 'required')),
+        userVerification: Schema.optional(Schema.Literal('discouraged', 'preferred', 'required')),
+    })),
+    userHandle: Schema.String,
+});
+export const PasskeySignupVerifyRequest = Schema.Struct({
+    email: Schema.String,
+    userHandle: Schema.String,
+    credential: Schema.Unknown, // RegistrationResponseJSON — shape varies by browser
+    deviceName: Schema.optional(Schema.String),
+});
+export const PasskeySignupVerifyResponse = Schema.Struct({
+    accessToken: Schema.String,
+    refreshToken: Schema.String,
+    expiresIn: Schema.Number,
+    user: Schema.Struct({
+        id: Schema.String,
+        email: Schema.String,
+        name: Schema.NullOr(Schema.String),
+        role: Schema.String,
+    }),
+    passkey: Schema.Struct({
+        id: Schema.String,
+        authenticatorAttachment: Schema.NullOr(Schema.Literal('platform', 'cross-platform')),
+        backupState: Schema.NullOr(Schema.Boolean),
+        aaguid: Schema.NullOr(Schema.String),
+    }),
+});
+export const PasskeyPolicyViolationResponse = Schema.Struct({
+    error: Schema.Literal('policy_violation'),
+    code: Schema.Literal('device_bound_required', 'aaguid_not_allowed'),
+    message: Schema.String,
+});
+export const PrimaryAuthMethodResponse = Schema.Struct({
+    userId: Schema.String,
+    primaryAuthMethod: Schema.Literal('passkey', 'password'),
+});
+// ============================================================================
+// Org Auth Policy — ADR-089 Phase 5.11 / S26
+// ============================================================================
+export const OrgAuthPolicy = Schema.Struct({
+    orgId: Schema.String,
+    requirePasskeyForSignup: Schema.Boolean,
+    requireDeviceBoundPasskeys: Schema.Boolean,
+    allowedAaguids: Schema.Array(Schema.String),
+    updatedAt: Schema.String,
+    updatedBy: Schema.NullOr(Schema.String),
+});
+export const OrgAuthPolicyUpdateRequest = Schema.Struct({
+    requirePasskeyForSignup: Schema.optional(Schema.Boolean),
+    requireDeviceBoundPasskeys: Schema.optional(Schema.Boolean),
+    allowedAaguids: Schema.optional(Schema.Array(Schema.String)),
+});