@sema-ai/registry-core 0.10.3

package/dist/api/auth-bridge.js

@@ -0,0 +1,211 @@
+/**
+ * `api/auth-bridge` — the 鉴权桥 contract: how a WORKER (sema-server / any data-plane service) verifies a
+ * registry-minted USER access JWT and maps it into its existing `x-agent-principal` identity system.
+ * (REGISTRY-REBUILD-DESIGN §5, M3 — registry half = JWKS already shipped; service half = ONE verifier
+ * middleware implementing the rules below. This file is the schema + normative spec the service copies.)
+ *
+ * TRUST MODEL (single trust root, zero new worker config): the worker already trusts the registry for its
+ * effective config; it extends the SAME trust to the registry's JWKS. A bearer token that is a well-formed
+ * JWT and verifies against that JWKS with the checks below IS the user — `sub` feeds x-agent-principal
+ * directly (owner semantics / costQuota / entitlement are already principal-keyed). Existing
+ * SERVICE_AUTH_TOKENS / wpt_ bearer branches are untouched; this is an ADDITIONAL branch tried when the
+ * bearer LOOKS like a JWT (three dot-separated base64url segments).
+ *
+ * ════════════════════════════════════════════════════════════════════════════════════════════════════════
+ * NORMATIVE VERIFICATION RULES — the service verifier MUST implement ALL of these (copy as its spec):
+ *
+ *  R1 ALGORITHM WHITELIST. Accept `alg: RS256` ONLY (AUTH_BRIDGE_ALGS). Reject `none`, every HS* (an
+ *     HS-signed token verified against a PUBLIC key = classic alg-confusion forgery), the ES and PS families, and any
+ *     token whose header alg is absent. Pin the list in the JWT library call — never read alg from the
+ *     token to decide how to verify.
+ *
+ *  R2 KEY SOURCE. Verification keys come from the registry JWKS endpoint `GET {registryBaseUrl}` +
+ *     REGISTRY_JWKS_PATH ("/api/auth/sso/jwks"; response shape = `Jwks` below, public members only:
+ *     kty/n/e/kid/use/alg). Match the token header `kid` against cached keys.
+ *
+ *  R3 KID-MISS FORCED REFRESH + THROTTLE. kid found in cache → use the cached key (no fetch on the hot
+ *     path). kid NOT in cache → force ONE JWKS refetch, then retry the match (this is the key-ROTATION
+ *     window: a freshly rotated registry would otherwise reject every new token until the cache expired).
+ *     Forced refreshes are throttled to at most one per `jwksRefreshMinIntervalSec` (default 60s) —
+ *     otherwise an attacker spraying random-kid tokens turns the verifier into a JWKS-fetch DoS cannon.
+ *     Within the throttle window an unknown kid fails as `invalid_signature` WITHOUT fetching.
+ *     (Decision function: `shouldForceJwksRefresh`.)
+ *
+ *  R4 ISSUER PIN. `iss` MUST equal the CONFIGURED issuer exactly (VerifierConfig.issuer = the registry's
+ *     SSO_ISSUER, trailing slash stripped on both sides). A missing or different iss → `unknown_issuer`.
+ *     Never derive the expected issuer from the token or from request headers.
+ *
+ *  R5 TIME WINDOW WITH SKEW. `exp` is REQUIRED: reject when nowSec > exp + clockSkewSec. `nbf`, when
+ *     present: reject when nowSec < nbf - clockSkewSec. clockSkewSec default 60 (DEFAULT_CLOCK_SKEW_SEC).
+ *     Both failures classify as `expired`. (Decision function: `classifyTimeClaims`.)
+ *
+ *  R6 PRINCIPAL. `sub` MUST be a non-empty string — it becomes `VerifiedIdentity.principal` and feeds the
+ *     existing x-agent-principal pipeline verbatim. Empty/missing sub → `malformed`.
+ *
+ *  R7 AUDIENCE (optional). When VerifierConfig.audience is set, `aud` must contain it (string equal or
+ *     array member); mismatch → `invalid_signature`-class rejection is WRONG — classify as `malformed`
+ *     (the token is valid but not FOR this worker). When audience is unset, `aud` is ignored.
+ *
+ *  R8 OFFLINE GRACE / FAIL-CLOSED. JWKS fetch fails (network/5xx/malformed body): keys already cached
+ *     remain USABLE for up to `offlineGraceSec` (default 24h, DEFAULT_OFFLINE_GRACE_SEC) measured from the
+ *     last SUCCESSFUL fetch — a registry blip must not take the whole data plane down. Past the grace, or
+ *     with no cache at all, verification fails CLOSED as `jwks_unavailable` (never fail-open, never skip
+ *     signature checks). (Decision function: `jwksWithinOfflineGrace`.)
+ *
+ *  R9 OUTPUT. Success → `VerifiedIdentity { principal: sub, role: token.role, grantId: token.jti,
+ *     scope: token.scope }` (`scope` = the multi-tenant active scope claim, `api/scopes`; absent = "global").
+ *     `role` is the registry RBAC role claim (string, informational for the worker's own authz mapping);
+ *     `grantId` is the jti when the registry stamps one (absent today — optional forever). Failure → one
+ *     of AUTH_BRIDGE_ERROR_CODES; the HTTP surface answers 401 with a GENERIC message (no error detail
+ *     disclosure to the caller; the code goes to logs/metrics only).
+ *
+ *  R10 NO CREDENTIAL LOGGING. Never log the token, any signature segment, or JWKS key material. Log
+ *      kid + error code + iss at most.
+ * ════════════════════════════════════════════════════════════════════════════════════════════════════════
+ *
+ * Pure zod contract + pure decision functions — zero IO, zero crypto here (the service brings its own JWT
+ * library; THESE shapes pin down its configuration), browser-safe.
+ */
+import { z } from "zod";
+// ── constants ────────────────────────────────────────────────────────────────────────────────────────────
+/** The registry JWKS endpoint, relative to the registry origin (shipped; public by design, RFC 7517 §5). */
+export const REGISTRY_JWKS_PATH = "/api/auth/sso/jwks";
+/** R1 — the ONLY acceptable JWS algorithms. */
+export const AUTH_BRIDGE_ALGS = ["RS256"];
+/** R5 — default tolerated clock skew (seconds) on exp/nbf. */
+export const DEFAULT_CLOCK_SKEW_SEC = 60;
+/** R3 — default minimum seconds between FORCED (kid-miss) JWKS refetches. */
+export const DEFAULT_JWKS_REFRESH_MIN_INTERVAL_SEC = 60;
+/** R8 — default seconds a cached JWKS stays usable after fetches start failing (24h), then fail-closed. */
+export const DEFAULT_OFFLINE_GRACE_SEC = 24 * 60 * 60;
+// ── JWKS wire shape (what GET /api/auth/sso/jwks returns) ────────────────────────────────────────────────
+/** One RSA public JWK as the registry publishes it (public members ONLY — a `d`/`p`/`q` here is a registry
+ *  bug, but the verifier MUST still never use/echo private members). */
+export const RegistryJwk = z
+    .object({
+    kty: z.literal("RSA"),
+    /** modulus, base64url */
+    n: z.string().min(1),
+    /** exponent, base64url */
+    e: z.string().min(1),
+    /** RFC 7638 thumbprint of the public JWK — the rotation-stable key id tokens carry in their header. */
+    kid: z.string().min(1),
+    use: z.literal("sig").optional(),
+    alg: z.enum(AUTH_BRIDGE_ALGS).optional(),
+})
+    .passthrough();
+/** The JWKS document. `{keys: []}` is VALID (registry with SSO disabled) — every token then fails as
+ *  `invalid_signature` (there is a registry, it just mints nothing). */
+export const RegistryJwks = z.object({ keys: z.array(RegistryJwk) }).passthrough();
+// ── verifier configuration ───────────────────────────────────────────────────────────────────────────────
+/** Everything the service verifier is allowed to be configured with. In the zero-new-config deployment the
+ *  worker derives `jwksUrl` from the registry base URL it already has (config pull) + REGISTRY_JWKS_PATH,
+ *  and `issuer` from the same registry identity — but both stay explicit here so a split deployment
+ *  (issuer behind a proxy ≠ fetch URL) is expressible. */
+export const VerifierConfig = z.object({
+    /** R4 — the EXACT expected `iss` (the registry's SSO_ISSUER). Compare with trailing slash stripped. */
+    issuer: z.string().min(1),
+    /** R2 — absolute JWKS URL. Default: issuer (or the worker's registry base URL) + REGISTRY_JWKS_PATH. */
+    jwksUrl: z.string().min(1).optional(),
+    /** R7 — when set, `aud` must contain this value; unset = aud ignored. */
+    audience: z.string().min(1).optional(),
+    /** R5 — seconds of exp/nbf tolerance. Default DEFAULT_CLOCK_SKEW_SEC (60). */
+    clockSkewSec: z.number().int().nonnegative().default(DEFAULT_CLOCK_SKEW_SEC),
+    /** R3 — min seconds between forced kid-miss refetches. Default 60. */
+    jwksRefreshMinIntervalSec: z.number().int().nonnegative().default(DEFAULT_JWKS_REFRESH_MIN_INTERVAL_SEC),
+    /** R8 — seconds a stale cache survives fetch failures before fail-closed. Default 86400 (24h). */
+    offlineGraceSec: z.number().int().nonnegative().default(DEFAULT_OFFLINE_GRACE_SEC),
+});
+// ── verification outcome ─────────────────────────────────────────────────────────────────────────────────
+/** R9 failure classification — for logs/metrics/tests; the HTTP surface stays a generic 401. */
+export const AUTH_BRIDGE_ERROR_CODES = [
+    /** exp in the past / nbf in the future (beyond clockSkewSec) — R5. */
+    "expired",
+    /** signature does not verify against any acceptable key, or kid unknown after the R3 refresh path. */
+    "invalid_signature",
+    /** iss missing or ≠ the configured issuer — R4. */
+    "unknown_issuer",
+    /** no usable JWKS: never fetched successfully, or offline grace exhausted — R8. Fail-closed. */
+    "jwks_unavailable",
+    /** not a JWT / disallowed alg (R1) / missing sub (R6) / aud mismatch (R7) / claim shape garbage. */
+    "malformed",
+];
+/** R9 success output — what the verifier middleware hands the existing principal pipeline. */
+export const VerifiedIdentity = z.object({
+    /** = token `sub`. Feeds x-agent-principal / owner semantics / costQuota / entitlement keying verbatim. */
+    principal: z.string().min(1),
+    /** = token `role` claim (registry RBAC: admin/editor/viewer/…) — informational; the worker maps it to
+     *  its own authz, it does NOT replace worker-side entitlement checks. */
+    role: z.string().optional(),
+    /** = token `jti` when present (the auth_grants grant id — audit correlation). Absent today; optional forever. */
+    grantId: z.string().optional(),
+    /** = token `scope` claim when present (the active tenant scope, `api/scopes`) — transparently forwarded
+     *  to the worker's principal pipeline. ABSENT means the pre-scope/default token: semantically "global"
+     *  (use `tokenScopeOf` from api/scopes to normalize). Optional forever — backward compatible. */
+    scope: z.string().optional(),
+});
+/**
+ * R3 — should a token bearing `kid` trigger a forced JWKS refetch?
+ * true  ⇔ the kid is not cached AND we are outside the refresh throttle window.
+ * false ⇒ verify against the cache as-is (cached kid hit), or fail `invalid_signature` (unknown kid,
+ *         throttled) without fetching.
+ */
+export function shouldForceJwksRefresh(kid, cache, cfg) {
+    if (cache.cachedKids.includes(kid))
+        return false;
+    if (cache.lastFetchAttemptMs === undefined)
+        return true;
+    return cache.nowMs - cache.lastFetchAttemptMs >= cfg.jwksRefreshMinIntervalSec * 1000;
+}
+/**
+ * R8 — with the LATEST fetch having failed, may the cached keys still be used?
+ * true  ⇔ there WAS a successful fetch and it is at most offlineGraceSec old.
+ * false ⇒ fail closed: `jwks_unavailable`.
+ */
+export function jwksWithinOfflineGrace(cache, cfg) {
+    if (cache.lastFetchSuccessMs === undefined)
+        return false;
+    return cache.nowMs - cache.lastFetchSuccessMs <= cfg.offlineGraceSec * 1000;
+}
+/**
+ * R5 — classify the token's time window. `exp` REQUIRED (a JWT without exp is not acceptable here —
+ * registry tokens always carry one; classify a missing exp as "expired" so it can never live forever).
+ * All values in SECONDS (JWT NumericDate).
+ */
+export function classifyTimeClaims(claims, nowSec, clockSkewSec) {
+    if (typeof claims.exp !== "number" || nowSec > claims.exp + clockSkewSec)
+        return "expired";
+    if (typeof claims.nbf === "number" && nowSec < claims.nbf - clockSkewSec)
+        return "expired";
+    return "ok";
+}
+/**
+ * R6/R7/R9 — map a signature-verified payload to the identity, or reject. Pure: call AFTER the JWT
+ * library has verified signature (R1/R2/R3), issuer (R4) and time (R5).
+ */
+export function toVerifiedIdentity(payload, cfg) {
+    if (typeof payload.sub !== "string" || payload.sub.length === 0)
+        return { ok: false, error: "malformed" };
+    if (cfg?.audience) {
+        const aud = payload.aud;
+        const match = typeof aud === "string" ? aud === cfg.audience : Array.isArray(aud) && aud.includes(cfg.audience);
+        if (!match)
+            return { ok: false, error: "malformed" };
+    }
+    return {
+        ok: true,
+        identity: {
+            principal: payload.sub,
+            role: typeof payload.role === "string" && payload.role.length > 0 ? payload.role : undefined,
+            grantId: typeof payload.jti === "string" && payload.jti.length > 0 ? payload.jti : undefined,
+            scope: typeof payload.scope === "string" && payload.scope.length > 0 ? payload.scope : undefined,
+        },
+    };
+}
+/** Cheap pre-filter: does this bearer LOOK like a JWT (three non-empty dot-separated segments)? Use it to
+ *  route between the existing static-token branch and this verifier — NOT as any kind of validation. */
+export function looksLikeJwt(bearer) {
+    const parts = bearer.split(".");
+    return parts.length === 3 && parts.every((p) => p.length > 0);
+}
+//# sourceMappingURL=auth-bridge.js.map

package/dist/api/auth-bridge.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth-bridge.js","sourceRoot":"","sources":["../../src/api/auth-bridge.ts"],"names":[],"mappings":"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"}

package/dist/api/auth.d.ts

@@ -0,0 +1,258 @@
+/**
+ * `api/auth` — the /api/v1/auth/* WIRE CONTRACT (REGISTRY-REBUILD-DESIGN §2.1/§2.2, M1 shipped in
+ * sema-registry; this file freezes the shipped shapes so registry, orchestrator, service and the sema
+ * shell import ONE source of truth — design §3 "契约先行").
+ *
+ * The flow is RFC 8628 (OAuth 2.0 Device Authorization Grant) + a rotating opaque refresh token:
+ *
+ *   1. client  POST /api/v1/auth/device/code            → DeviceCodeResponse (device_code + user_code)
+ *   2. user    opens verification_uri (/activate) in ANY logged-in browser, approves the user_code
+ *              (GET/POST /api/v1/auth/device/approve — session-cookie-gated, consent screen)
+ *   3. client  POLLS POST /api/v1/auth/device/token every `interval` seconds
+ *              → 400 OAuthErrorResponse (authorization_pending / slow_down / expired_token / access_denied)
+ *              → 200 TokenGrantResponse exactly ONCE (the handshake row is consumed atomically)
+ *   4. client  silently renews via POST /api/v1/auth/token/refresh (refresh rotation: the presented
+ *              refresh token is single-use; a replay answers invalid_grant)
+ *   5. client  POST /api/v1/auth/logout revokes the refresh grant (RFC 7009 discipline: always 200 ok,
+ *              no token-existence disclosure)
+ *
+ * WIRE CASING: these are OAuth-standard endpoints — fields are snake_case ON THE WIRE (access_token,
+ * device_code, …), deliberately breaking this package's camelCase habit. Do not "fix" it.
+ *
+ * SECRET DISCIPLINE (registry side, informational for consumers): device_code and refresh_token are
+ * ≥256-bit opaque strings persisted ONLY as SHA-256 hashes; access_token is the standard issueSsoToken
+ * RS256 JWT (1h) — see `api/auth-bridge` for how a worker verifies it.
+ *
+ * Pure zod contract — zero IO, browser-safe, same rules as the rest of this package.
+ */
+import { z } from "zod";
+/** The five auth endpoints, relative to the registry origin. */
+export declare const AUTH_V1_PATHS: {
+    readonly deviceCode: "/api/v1/auth/device/code";
+    readonly deviceToken: "/api/v1/auth/device/token";
+    readonly deviceApprove: "/api/v1/auth/device/approve";
+    readonly tokenRefresh: "/api/v1/auth/token/refresh";
+    readonly logout: "/api/v1/auth/logout";
+};
+/** The RFC 8628 grant_type the device token endpoint requires. */
+export declare const DEVICE_GRANT_TYPE = "urn:ietf:params:oauth:grant-type:device_code";
+/** Minimum seconds between token-endpoint polls (RFC 8628 `interval`); polling faster → `slow_down`. */
+export declare const DEVICE_POLL_INTERVAL_SECONDS = 5;
+/** Device-code handshake lifetime (seconds) — the user has 15 minutes to open /activate and approve. */
+export declare const DEVICE_CODE_TTL_SECONDS: number;
+/** Access-token (RS256 JWT) lifetime in seconds — 1h, re-minted via refresh. */
+export declare const ACCESS_TOKEN_TTL_SECONDS: number;
+/** Refresh-grant lifetime (seconds) — 30d SLIDING: every rotation opens a fresh 30d window. */
+export declare const REFRESH_TOKEN_TTL_SECONDS: number;
+/** Every error code the /api/v1/auth/* endpoints answer (HTTP 400 unless noted). */
+export declare const OAUTH_ERROR_CODES: readonly ["authorization_pending", "slow_down", "expired_token", "access_denied", "invalid_request", "unsupported_grant_type", "invalid_grant", "server_error"];
+export type OAuthErrorCode = (typeof OAUTH_ERROR_CODES)[number];
+/** The uniform error body. `error_description` is HUMAN diagnostic text — clients branch on `error` only. */
+export declare const OAuthErrorResponse: z.ZodObject<{
+    error: z.ZodEnum<["authorization_pending", "slow_down", "expired_token", "access_denied", "invalid_request", "unsupported_grant_type", "invalid_grant", "server_error"]>;
+    error_description: z.ZodOptional<z.ZodString>;
+}, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+    error: z.ZodEnum<["authorization_pending", "slow_down", "expired_token", "access_denied", "invalid_request", "unsupported_grant_type", "invalid_grant", "server_error"]>;
+    error_description: z.ZodOptional<z.ZodString>;
+}, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+    error: z.ZodEnum<["authorization_pending", "slow_down", "expired_token", "access_denied", "invalid_request", "unsupported_grant_type", "invalid_grant", "server_error"]>;
+    error_description: z.ZodOptional<z.ZodString>;
+}, z.ZodTypeAny, "passthrough">>;
+export type OAuthErrorResponse = z.infer<typeof OAuthErrorResponse>;
+/** Unauthenticated by design (the client has no credentials yet). `client_name` is a NON-secret display
+ *  hint for the consent screen ("sema CLI on macOS"); absent → the server falls back to the User-Agent.
+ *  Body may be JSON or form-encoded; an empty body is legal. */
+export declare const DeviceCodeRequest: z.ZodObject<{
+    client_name: z.ZodOptional<z.ZodString>;
+}, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+    client_name: z.ZodOptional<z.ZodString>;
+}, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+    client_name: z.ZodOptional<z.ZodString>;
+}, z.ZodTypeAny, "passthrough">>;
+export type DeviceCodeRequest = z.infer<typeof DeviceCodeRequest>;
+/** RFC 8628 §3.2 device-authorization response. `device_code` is the client's polling secret (keep it in
+ *  memory, never log it); `user_code` is the short human code ("XXXX-XXXX") the user approves. */
+export declare const DeviceCodeResponse: z.ZodObject<{
+    /** ≥256-bit opaque polling secret — returned ONCE, hash-persisted server-side. */
+    device_code: z.ZodString;
+    /** Human approval code, canonical shape "XXXX-XXXX" (base-20 alphabet: no vowels, no 0/O/1/I). */
+    user_code: z.ZodString;
+    /** The /activate page the user opens (any device, any logged-in browser). */
+    verification_uri: z.ZodString;
+    /** verification_uri with ?user_code= pre-filled — one-click / QR path. */
+    verification_uri_complete: z.ZodString;
+    /** Seconds until the handshake expires (DEVICE_CODE_TTL_SECONDS). */
+    expires_in: z.ZodNumber;
+    /** Minimum seconds between polls (DEVICE_POLL_INTERVAL_SECONDS). */
+    interval: z.ZodNumber;
+}, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+    /** ≥256-bit opaque polling secret — returned ONCE, hash-persisted server-side. */
+    device_code: z.ZodString;
+    /** Human approval code, canonical shape "XXXX-XXXX" (base-20 alphabet: no vowels, no 0/O/1/I). */
+    user_code: z.ZodString;
+    /** The /activate page the user opens (any device, any logged-in browser). */
+    verification_uri: z.ZodString;
+    /** verification_uri with ?user_code= pre-filled — one-click / QR path. */
+    verification_uri_complete: z.ZodString;
+    /** Seconds until the handshake expires (DEVICE_CODE_TTL_SECONDS). */
+    expires_in: z.ZodNumber;
+    /** Minimum seconds between polls (DEVICE_POLL_INTERVAL_SECONDS). */
+    interval: z.ZodNumber;
+}, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+    /** ≥256-bit opaque polling secret — returned ONCE, hash-persisted server-side. */
+    device_code: z.ZodString;
+    /** Human approval code, canonical shape "XXXX-XXXX" (base-20 alphabet: no vowels, no 0/O/1/I). */
+    user_code: z.ZodString;
+    /** The /activate page the user opens (any device, any logged-in browser). */
+    verification_uri: z.ZodString;
+    /** verification_uri with ?user_code= pre-filled — one-click / QR path. */
+    verification_uri_complete: z.ZodString;
+    /** Seconds until the handshake expires (DEVICE_CODE_TTL_SECONDS). */
+    expires_in: z.ZodNumber;
+    /** Minimum seconds between polls (DEVICE_POLL_INTERVAL_SECONDS). */
+    interval: z.ZodNumber;
+}, z.ZodTypeAny, "passthrough">>;
+export type DeviceCodeResponse = z.infer<typeof DeviceCodeResponse>;
+/** RFC 8628 §3.4 token request. Form or JSON. */
+export declare const DeviceTokenRequest: z.ZodObject<{
+    grant_type: z.ZodLiteral<"urn:ietf:params:oauth:grant-type:device_code">;
+    device_code: z.ZodString;
+}, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+    grant_type: z.ZodLiteral<"urn:ietf:params:oauth:grant-type:device_code">;
+    device_code: z.ZodString;
+}, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+    grant_type: z.ZodLiteral<"urn:ietf:params:oauth:grant-type:device_code">;
+    device_code: z.ZodString;
+}, z.ZodTypeAny, "passthrough">>;
+export type DeviceTokenRequest = z.infer<typeof DeviceTokenRequest>;
+/** The ONE token success shape — shared by device/token AND token/refresh (both mint through the same
+ *  exit: access = issueSsoToken RS256 JWT, refresh = fresh opaque rotating grant). */
+export declare const TokenGrantResponse: z.ZodObject<{
+    /** RS256 JWT — claims: sub (principal), iss, iat, exp, role; optional aud. Verify per api/auth-bridge. */
+    access_token: z.ZodString;
+    /** NEW opaque rotating refresh token — replaces any previous one the client held. Store 0600/keychain. */
+    refresh_token: z.ZodString;
+    token_type: z.ZodLiteral<"Bearer">;
+    /** Access-token lifetime in seconds (ACCESS_TOKEN_TTL_SECONDS). */
+    expires_in: z.ZodNumber;
+}, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+    /** RS256 JWT — claims: sub (principal), iss, iat, exp, role; optional aud. Verify per api/auth-bridge. */
+    access_token: z.ZodString;
+    /** NEW opaque rotating refresh token — replaces any previous one the client held. Store 0600/keychain. */
+    refresh_token: z.ZodString;
+    token_type: z.ZodLiteral<"Bearer">;
+    /** Access-token lifetime in seconds (ACCESS_TOKEN_TTL_SECONDS). */
+    expires_in: z.ZodNumber;
+}, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+    /** RS256 JWT — claims: sub (principal), iss, iat, exp, role; optional aud. Verify per api/auth-bridge. */
+    access_token: z.ZodString;
+    /** NEW opaque rotating refresh token — replaces any previous one the client held. Store 0600/keychain. */
+    refresh_token: z.ZodString;
+    token_type: z.ZodLiteral<"Bearer">;
+    /** Access-token lifetime in seconds (ACCESS_TOKEN_TTL_SECONDS). */
+    expires_in: z.ZodNumber;
+}, z.ZodTypeAny, "passthrough">>;
+export type TokenGrantResponse = z.infer<typeof TokenGrantResponse>;
+/** Rotation is STRICT single-use: success revokes the presented grant and returns a NEW refresh_token;
+ *  a replayed (or raced) old token answers `invalid_grant`. Clients MUST persist the new token before
+ *  discarding the old request state. */
+export declare const TokenRefreshRequest: z.ZodObject<{
+    refresh_token: z.ZodString;
+}, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+    refresh_token: z.ZodString;
+}, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+    refresh_token: z.ZodString;
+}, z.ZodTypeAny, "passthrough">>;
+export type TokenRefreshRequest = z.infer<typeof TokenRefreshRequest>;
+/** Revoke the refresh grant. The already-minted access JWT stays valid until its 1h exp — revocation kills
+ *  the RENEWAL path, which is the durable one. */
+export declare const LogoutRequest: z.ZodObject<{
+    refresh_token: z.ZodString;
+}, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+    refresh_token: z.ZodString;
+}, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+    refresh_token: z.ZodString;
+}, z.ZodTypeAny, "passthrough">>;
+export type LogoutRequest = z.infer<typeof LogoutRequest>;
+/** Always `{ok:true}` with HTTP 200 whether or not the token matched a live grant (RFC 7009: a revocation
+ *  endpoint never discloses token existence). 400 only for a malformed request. */
+export declare const LogoutResponse: z.ZodObject<{
+    ok: z.ZodLiteral<true>;
+}, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+    ok: z.ZodLiteral<true>;
+}, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+    ok: z.ZodLiteral<true>;
+}, z.ZodTypeAny, "passthrough">>;
+export type LogoutResponse = z.infer<typeof LogoutResponse>;
+/** Handshake states a consent-screen lookup can see. (`approved` rows vanish once exchanged/consumed.)
+ *  `denied` is contract-reserved for an explicit deny button (pairs with the `access_denied` poll error);
+ *  the shipped M1 store carries pending|approved only — adding deny later is implementation, not schema. */
+export declare const DEVICE_AUTH_STATUSES: readonly ["pending", "approved", "denied"];
+export type DeviceAuthStatus = (typeof DEVICE_AUTH_STATUSES)[number];
+/** GET ?user_code=XXXX-XXXX — the consent screen's lookup, WITHOUT approving. 401 when not signed in;
+ *  invalid_grant for an unknown/expired code. */
+export declare const DeviceApproveLookupResponse: z.ZodObject<{
+    user_code: z.ZodString;
+    status: z.ZodEnum<["pending", "approved", "denied"]>;
+    /** The client_name/User-Agent display hint from device/code — null when the client sent none. */
+    client: z.ZodNullable<z.ZodString>;
+    /** Handshake expiry, epoch MILLISECONDS. */
+    expires_at: z.ZodNumber;
+}, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+    user_code: z.ZodString;
+    status: z.ZodEnum<["pending", "approved", "denied"]>;
+    /** The client_name/User-Agent display hint from device/code — null when the client sent none. */
+    client: z.ZodNullable<z.ZodString>;
+    /** Handshake expiry, epoch MILLISECONDS. */
+    expires_at: z.ZodNumber;
+}, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+    user_code: z.ZodString;
+    status: z.ZodEnum<["pending", "approved", "denied"]>;
+    /** The client_name/User-Agent display hint from device/code — null when the client sent none. */
+    client: z.ZodNullable<z.ZodString>;
+    /** Handshake expiry, epoch MILLISECONDS. */
+    expires_at: z.ZodNumber;
+}, z.ZodTypeAny, "passthrough">>;
+export type DeviceApproveLookupResponse = z.infer<typeof DeviceApproveLookupResponse>;
+/** POST body (JSON ONLY — the JSON content type is part of the cross-site-request defence; a cross-site
+ *  form cannot send application/json without a CORS preflight). The approving identity comes from the
+ *  session cookie exclusively — NEVER from this body. */
+export declare const DeviceApproveRequest: z.ZodObject<{
+    /** Case-insensitive; dashes/spaces optional — see normalizeUserCode. */
+    user_code: z.ZodString;
+}, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+    /** Case-insensitive; dashes/spaces optional — see normalizeUserCode. */
+    user_code: z.ZodString;
+}, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+    /** Case-insensitive; dashes/spaces optional — see normalizeUserCode. */
+    user_code: z.ZodString;
+}, z.ZodTypeAny, "passthrough">>;
+export type DeviceApproveRequest = z.infer<typeof DeviceApproveRequest>;
+export declare const DeviceApproveResponse: z.ZodObject<{
+    ok: z.ZodLiteral<true>;
+    user_code: z.ZodString;
+}, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+    ok: z.ZodLiteral<true>;
+    user_code: z.ZodString;
+}, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+    ok: z.ZodLiteral<true>;
+    user_code: z.ZodString;
+}, z.ZodTypeAny, "passthrough">>;
+export type DeviceApproveResponse = z.infer<typeof DeviceApproveResponse>;
+/**
+ * Canonicalize a human-typed user code to the wire shape "XXXX-XXXX": uppercase, dashes/spaces optional.
+ * null = not a plausible code (wrong length/charset after stripping separators). Same normalization the
+ * server applies — run it client-side for instant feedback.
+ */
+export declare function normalizeUserCode(input: unknown): string | null;
+/**
+ * The RFC 8628 §3.5 poll-loop step: what interval to poll with next, and whether to keep going.
+ * - authorization_pending → keep polling at the current interval
+ * - slow_down             → keep polling, interval + 5s (the RFC-mandated increment)
+ * - anything else         → stop (expired_token/access_denied = terminal; invalid_* = client bug)
+ */
+export declare function nextPollInterval(currentIntervalSeconds: number, error: OAuthErrorCode): {
+    continue: boolean;
+    intervalSeconds: number;
+};
+//# sourceMappingURL=auth.d.ts.map

package/dist/api/auth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../../src/api/auth.ts"],"names":[],"mappings":"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"}