@sema-agent/settings-schema 1.0.0

package/dist/api/scopes.d.ts

@@ -0,0 +1,344 @@
+/**
+ * `api/scopes` — the MULTI-TENANT SCOPE wire contract for the registry (/api/v1/scopes* +
+ * /api/v1/auth/scope). Frozen here so sema-registry (the implementation), the orchestrator, workers and
+ * the sema shell import ONE source of truth — same "契约先行" discipline as `api/auth`.
+ *
+ * THE SCOPE MODEL (normative — the registry implements EXACTLY this):
+ *
+ *  - A **scope** is a tenant boundary: `{id, name, createdAt}`. `id` is a slug (SCOPE_ID_REGEX).
+ *    The reserved id `"global"` (GLOBAL_SCOPE) is the DEFAULT scope: it always exists, is never
+ *    created via the API (ScopeCreateRequest rejects it) and is never deleted.
+ *  - **Membership** is per-scope: `{scopeId, principal, role}` where role is the existing 4-level
+ *    RBAC ladder (viewer < editor < publisher < admin). The SAME principal may be `editor` in scope A
+ *    and `viewer` in scope B.
+ *  - The **instance-level** `users.role` is unchanged and orthogonal: an instance `admin` administers
+ *    ALL scopes — inside any scope their effective role is always `"admin"` (see effectiveScopeRole).
+ *  - The **access JWT** gains an OPTIONAL `scope` claim (SCOPE_CLAIM) binding the token to its active
+ *    scope. A token WITHOUT the claim means `"global"` (tokenScopeOf) — full backward compatibility:
+ *    every pre-scope token keeps working, scoped to global. The refresh token is NOT scope-bound;
+ *    refresh re-mints per resolveTokenScope, and the client re-switches if it wants another scope.
+ *
+ * ENDPOINTS (paths in SCOPES_V1_PATHS / scopeMembersPath):
+ *
+ *   GET    /api/v1/scopes                → ScopesListResponse {scopes:[{id,name,role}]} — the CALLER's
+ *          scopes with their per-scope effective role (instance admin sees ALL scopes, role "admin").
+ *   POST   /api/v1/auth/scope            → switch active scope: ScopeSwitchRequest {scope} →
+ *          ScopeSwitchResponse {access_token, token_type:"Bearer", expires_in, scope, role}; errors are
+ *          OAuth-style OAuthErrorResponse (`invalid_request` = malformed / unknown scope shape,
+ *          `access_denied` = caller is not a member and not an instance admin — canSwitchScope).
+ *          Auth: a valid access token (any scope). Mints a NEW access token bound to `scope`; the
+ *          caller's refresh grant is untouched.
+ *   POST   /api/v1/scopes                → create a scope (instance admin only): ScopeCreateRequest
+ *          {id,name} → ScopeCreateResponse (the created Scope).
+ *   PUT    /api/v1/scopes/{id}/members   → upsert a member (instance admin only): ScopeMemberUpsertRequest
+ *          {principal, role} → ScopeMemberUpsertResponse (the stored membership row).
+ *   DELETE /api/v1/scopes/{id}/members   → remove a member (instance admin only): ScopeMemberDeleteRequest
+ *          {principal} → ScopeMemberDeleteResponse {ok:true} (idempotent — removing a non-member is 200).
+ *
+ * WIRE CASING: /api/v1/auth/scope is part of the OAuth face — snake_case on the wire (access_token,
+ * expires_in), matching `api/auth`. The /api/v1/scopes management face uses this package's camelCase
+ * (createdAt, scopeId) — it is a registry management API, not an OAuth endpoint.
+ *
+ * Pure zod contract + pure decision functions — zero IO, browser-safe. The decision functions
+ * (resolveTokenScope / canSwitchScope / effectiveScopeRole) are THE semantics: the registry
+ * implementation imports and calls these — it must not re-implement them.
+ */
+import { z } from "zod";
+import { type UserRole } from "../config-fns.js";
+/** The reserved default scope. Always exists; every token without a `scope` claim lives here. */
+export declare const GLOBAL_SCOPE = "global";
+/** Scope ids that can never be created (or deleted) through the API. */
+export declare const RESERVED_SCOPE_IDS: readonly ["global"];
+/** Slug shape for scope ids: lowercase alphanumeric + inner dashes, 1–64 chars, no leading/trailing dash. */
+export declare const SCOPE_ID_REGEX: RegExp;
+export { SCOPES_V1_PATHS, SCOPE_CLAIM } from "./wire.js";
+/** `/api/v1/scopes/{id}/members` for PUT (upsert) and DELETE (remove). */
+export declare function scopeMembersPath(scopeId: string): string;
+/** True for ids the API refuses to create/delete ("global"). */
+export declare function isReservedScopeId(id: string): boolean;
+/** A scope id on the wire — slug-validated. (The reserved "global" IS a valid ScopeId: it exists as an
+ *  entity everywhere except the create endpoint.) */
+export declare const ScopeId: z.ZodString;
+export type ScopeId = z.infer<typeof ScopeId>;
+/** The per-scope role ladder = the existing instance RBAC ladder (viewer < editor < publisher < admin). */
+export declare const ScopeRole: z.ZodEnum<[UserRole, ...UserRole[]]>;
+export type ScopeRole = UserRole;
+/** The scope entity. */
+export declare const Scope: z.ZodObject<{
+    id: z.ZodString;
+    /** Human display name (non-unique, non-secret). */
+    name: z.ZodString;
+    /** Creation time, epoch MILLISECONDS. The reserved "global" scope reports its provisioning time. */
+    createdAt: z.ZodNumber;
+}, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+    id: z.ZodString;
+    /** Human display name (non-unique, non-secret). */
+    name: z.ZodString;
+    /** Creation time, epoch MILLISECONDS. The reserved "global" scope reports its provisioning time. */
+    createdAt: z.ZodNumber;
+}, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+    id: z.ZodString;
+    /** Human display name (non-unique, non-secret). */
+    name: z.ZodString;
+    /** Creation time, epoch MILLISECONDS. The reserved "global" scope reports its provisioning time. */
+    createdAt: z.ZodNumber;
+}, z.ZodTypeAny, "passthrough">>;
+export type Scope = z.infer<typeof Scope>;
+/** One membership row: `principal` holds `role` inside `scopeId`. Per-scope — the same principal may
+ *  hold different roles in different scopes. */
+export declare const ScopeMember: z.ZodObject<{
+    scopeId: z.ZodString;
+    /** The user identity — same principal string the JWT `sub` / x-agent-principal pipeline uses. */
+    principal: z.ZodString;
+    role: z.ZodEnum<[UserRole, ...UserRole[]]>;
+}, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+    scopeId: z.ZodString;
+    /** The user identity — same principal string the JWT `sub` / x-agent-principal pipeline uses. */
+    principal: z.ZodString;
+    role: z.ZodEnum<[UserRole, ...UserRole[]]>;
+}, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+    scopeId: z.ZodString;
+    /** The user identity — same principal string the JWT `sub` / x-agent-principal pipeline uses. */
+    principal: z.ZodString;
+    role: z.ZodEnum<[UserRole, ...UserRole[]]>;
+}, z.ZodTypeAny, "passthrough">>;
+export type ScopeMember = z.infer<typeof ScopeMember>;
+/** One list entry: a scope the caller can act in, with the caller's EFFECTIVE role there
+ *  (effectiveScopeRole — instance admins list every scope with role "admin"). */
+export declare const ScopeListEntry: z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodString;
+    role: z.ZodEnum<[UserRole, ...UserRole[]]>;
+}, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+    id: z.ZodString;
+    name: z.ZodString;
+    role: z.ZodEnum<[UserRole, ...UserRole[]]>;
+}, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+    id: z.ZodString;
+    name: z.ZodString;
+    role: z.ZodEnum<[UserRole, ...UserRole[]]>;
+}, z.ZodTypeAny, "passthrough">>;
+export type ScopeListEntry = z.infer<typeof ScopeListEntry>;
+export declare const ScopesListResponse: z.ZodObject<{
+    scopes: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        name: z.ZodString;
+        role: z.ZodEnum<[UserRole, ...UserRole[]]>;
+    }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+        id: z.ZodString;
+        name: z.ZodString;
+        role: z.ZodEnum<[UserRole, ...UserRole[]]>;
+    }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+        id: z.ZodString;
+        name: z.ZodString;
+        role: z.ZodEnum<[UserRole, ...UserRole[]]>;
+    }, z.ZodTypeAny, "passthrough">>, "many">;
+}, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+    scopes: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        name: z.ZodString;
+        role: z.ZodEnum<[UserRole, ...UserRole[]]>;
+    }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+        id: z.ZodString;
+        name: z.ZodString;
+        role: z.ZodEnum<[UserRole, ...UserRole[]]>;
+    }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+        id: z.ZodString;
+        name: z.ZodString;
+        role: z.ZodEnum<[UserRole, ...UserRole[]]>;
+    }, z.ZodTypeAny, "passthrough">>, "many">;
+}, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+    scopes: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        name: z.ZodString;
+        role: z.ZodEnum<[UserRole, ...UserRole[]]>;
+    }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+        id: z.ZodString;
+        name: z.ZodString;
+        role: z.ZodEnum<[UserRole, ...UserRole[]]>;
+    }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+        id: z.ZodString;
+        name: z.ZodString;
+        role: z.ZodEnum<[UserRole, ...UserRole[]]>;
+    }, z.ZodTypeAny, "passthrough">>, "many">;
+}, z.ZodTypeAny, "passthrough">>;
+export type ScopesListResponse = z.infer<typeof ScopesListResponse>;
+/** Request: the target scope. Errors: `invalid_request` (malformed), `access_denied` (not a member and
+ *  not an instance admin — canSwitchScope false). */
+export declare const ScopeSwitchRequest: z.ZodObject<{
+    scope: z.ZodString;
+}, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+    scope: z.ZodString;
+}, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+    scope: z.ZodString;
+}, z.ZodTypeAny, "passthrough">>;
+export type ScopeSwitchRequest = z.infer<typeof ScopeSwitchRequest>;
+/** A fresh access token bound to the requested scope (`scope` claim = `scope` field below). The refresh
+ *  grant is untouched — this endpoint never returns a refresh_token. `role` = the caller's effective role
+ *  inside the new scope (effectiveScopeRole). */
+export declare const ScopeSwitchResponse: z.ZodObject<{
+    /** RS256 JWT with the `scope` claim set — verify per api/auth-bridge; VerifiedIdentity.scope carries it. */
+    access_token: z.ZodString;
+    token_type: z.ZodLiteral<"Bearer">;
+    /** Access-token lifetime in seconds (ACCESS_TOKEN_TTL_SECONDS — same mint as api/auth). */
+    expires_in: z.ZodNumber;
+    scope: z.ZodString;
+    role: z.ZodEnum<[UserRole, ...UserRole[]]>;
+}, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+    /** RS256 JWT with the `scope` claim set — verify per api/auth-bridge; VerifiedIdentity.scope carries it. */
+    access_token: z.ZodString;
+    token_type: z.ZodLiteral<"Bearer">;
+    /** Access-token lifetime in seconds (ACCESS_TOKEN_TTL_SECONDS — same mint as api/auth). */
+    expires_in: z.ZodNumber;
+    scope: z.ZodString;
+    role: z.ZodEnum<[UserRole, ...UserRole[]]>;
+}, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+    /** RS256 JWT with the `scope` claim set — verify per api/auth-bridge; VerifiedIdentity.scope carries it. */
+    access_token: z.ZodString;
+    token_type: z.ZodLiteral<"Bearer">;
+    /** Access-token lifetime in seconds (ACCESS_TOKEN_TTL_SECONDS — same mint as api/auth). */
+    expires_in: z.ZodNumber;
+    scope: z.ZodString;
+    role: z.ZodEnum<[UserRole, ...UserRole[]]>;
+}, z.ZodTypeAny, "passthrough">>;
+export type ScopeSwitchResponse = z.infer<typeof ScopeSwitchResponse>;
+/** Re-exported convenience: the switch endpoint mints through the SAME exit as api/auth (1h JWT). */
+export declare const SCOPE_SWITCH_TOKEN_TTL_SECONDS: number;
+/** Reserved ids ("global") are rejected AT THE SCHEMA — the default scope pre-exists and is not creatable. */
+export declare const ScopeCreateRequest: z.ZodObject<{
+    id: z.ZodEffects<z.ZodString, string, string>;
+    name: z.ZodString;
+}, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+    id: z.ZodEffects<z.ZodString, string, string>;
+    name: z.ZodString;
+}, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+    id: z.ZodEffects<z.ZodString, string, string>;
+    name: z.ZodString;
+}, z.ZodTypeAny, "passthrough">>;
+export type ScopeCreateRequest = z.infer<typeof ScopeCreateRequest>;
+/** The created scope, as stored. */
+export declare const ScopeCreateResponse: z.ZodObject<{
+    id: z.ZodString;
+    /** Human display name (non-unique, non-secret). */
+    name: z.ZodString;
+    /** Creation time, epoch MILLISECONDS. The reserved "global" scope reports its provisioning time. */
+    createdAt: z.ZodNumber;
+}, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+    id: z.ZodString;
+    /** Human display name (non-unique, non-secret). */
+    name: z.ZodString;
+    /** Creation time, epoch MILLISECONDS. The reserved "global" scope reports its provisioning time. */
+    createdAt: z.ZodNumber;
+}, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+    id: z.ZodString;
+    /** Human display name (non-unique, non-secret). */
+    name: z.ZodString;
+    /** Creation time, epoch MILLISECONDS. The reserved "global" scope reports its provisioning time. */
+    createdAt: z.ZodNumber;
+}, z.ZodTypeAny, "passthrough">>;
+export type ScopeCreateResponse = Scope;
+/** PUT body — upsert: sets `principal`'s role in the path scope, creating or replacing the row. */
+export declare const ScopeMemberUpsertRequest: z.ZodObject<{
+    principal: z.ZodString;
+    role: z.ZodEnum<[UserRole, ...UserRole[]]>;
+}, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+    principal: z.ZodString;
+    role: z.ZodEnum<[UserRole, ...UserRole[]]>;
+}, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+    principal: z.ZodString;
+    role: z.ZodEnum<[UserRole, ...UserRole[]]>;
+}, z.ZodTypeAny, "passthrough">>;
+export type ScopeMemberUpsertRequest = z.infer<typeof ScopeMemberUpsertRequest>;
+/** The stored membership row (scopeId echoes the path). */
+export declare const ScopeMemberUpsertResponse: z.ZodObject<{
+    scopeId: z.ZodString;
+    /** The user identity — same principal string the JWT `sub` / x-agent-principal pipeline uses. */
+    principal: z.ZodString;
+    role: z.ZodEnum<[UserRole, ...UserRole[]]>;
+}, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+    scopeId: z.ZodString;
+    /** The user identity — same principal string the JWT `sub` / x-agent-principal pipeline uses. */
+    principal: z.ZodString;
+    role: z.ZodEnum<[UserRole, ...UserRole[]]>;
+}, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+    scopeId: z.ZodString;
+    /** The user identity — same principal string the JWT `sub` / x-agent-principal pipeline uses. */
+    principal: z.ZodString;
+    role: z.ZodEnum<[UserRole, ...UserRole[]]>;
+}, z.ZodTypeAny, "passthrough">>;
+export type ScopeMemberUpsertResponse = ScopeMember;
+/** DELETE body — remove `principal` from the path scope. */
+export declare const ScopeMemberDeleteRequest: z.ZodObject<{
+    principal: z.ZodString;
+}, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+    principal: z.ZodString;
+}, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+    principal: z.ZodString;
+}, z.ZodTypeAny, "passthrough">>;
+export type ScopeMemberDeleteRequest = z.infer<typeof ScopeMemberDeleteRequest>;
+/** Idempotent: `{ok:true}` whether or not the principal was a member (no membership disclosure beyond
+ *  what the admin caller already sees). */
+export declare const ScopeMemberDeleteResponse: 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 ScopeMemberDeleteResponse = z.infer<typeof ScopeMemberDeleteResponse>;
+/** A membership as the decision functions see it (a projection of ScopeMember). */
+export interface ScopeMembershipInput {
+    scopeId: string;
+    role: UserRole;
+}
+/** What token minting resolved: the scope to stamp into the `scope` claim + the `role` claim value. */
+export interface ResolvedTokenScope {
+    scope: string;
+    role: string;
+}
+/**
+ * THE instance-admin override rule, in one place:
+ *
+ *   **An instance `admin`'s effective role inside ANY scope is always `"admin"`** — regardless of whether
+ *   they hold a membership there or what that membership says. For everyone else the effective role is
+ *   exactly their membership role (`membershipRole`), and `undefined` when they have no membership.
+ *
+ * `instanceRole` is the instance-level users.role string; only the exact value `"admin"` triggers the
+ * override (publisher/editor/viewer at instance level grant NO cross-scope power).
+ */
+export declare function effectiveScopeRole(membershipRole: UserRole | undefined, instanceRole: string): UserRole | undefined;
+/**
+ * THE token-minting scope decision — which scope (and role claim) a fresh access token binds to, given
+ * the principal's scope memberships and instance role. Deterministic; the registry (Node/Next) imports
+ * and calls this at every mint (device-flow grant AND refresh). NORMATIVE RULES (verbatim, 任务书拍定):
+ *
+ *   1. **唯一成员 scope** — exactly one membership → bind that scope, role = that membership's effective
+ *      role (effectiveScopeRole: instance admin ⇒ "admin").
+ *   2. **多个含 global** — multiple memberships, one of them "global" → bind "global", role = the global
+ *      membership's effective role.
+ *   3. **多个不含 global** — multiple memberships, none "global" → bind the scope whose id is FIRST in
+ *      lexicographic (UTF-16 code-unit) order — deterministic, no wall-clock/insertion-order dependence;
+ *      role = that membership's effective role.
+ *   4. **零成员** — no memberships → `{scope: "global", role: instanceRole}` (the instance role IS the
+ *      role claim, exactly as pre-scope tokens behaved — full backward compatibility).
+ *
+ * Duplicate scopeIds in the input: the entry that sorts first (by scopeId, then by role string) wins —
+ * callers should not pass duplicates, but the function stays deterministic if they do.
+ */
+export declare function resolveTokenScope(memberships: readonly ScopeMembershipInput[], instanceRole: string): ResolvedTokenScope;
+/**
+ * THE scope-switch authorization decision (POST /api/v1/auth/scope): allowed ⇔ the caller is a MEMBER of
+ * `targetScope` (any role) OR an instance `admin` (who may enter any scope, including ones they are not
+ * a member of — their effective role there is "admin" per effectiveScopeRole). Everyone else →
+ * `access_denied`. Note: "global" gets NO special-case here — a multi-scope user without a global
+ * membership cannot switch to global (their default mint never lands there either, rule 3 above).
+ */
+export declare function canSwitchScope(memberships: readonly ScopeMembershipInput[], instanceRole: string, targetScope: string): boolean;
+/**
+ * Read the active scope off verified JWT claims: a non-empty string `scope` claim, else GLOBAL_SCOPE.
+ * This is the ONE place the "missing claim = global" backward-compat rule lives — workers and the
+ * registry both call this instead of defaulting ad hoc.
+ */
+export declare function tokenScopeOf(claims: {
+    scope?: unknown;
+}): string;

package/dist/api/scopes.js

@@ -0,0 +1,222 @@
+/**
+ * `api/scopes` — the MULTI-TENANT SCOPE wire contract for the registry (/api/v1/scopes* +
+ * /api/v1/auth/scope). Frozen here so sema-registry (the implementation), the orchestrator, workers and
+ * the sema shell import ONE source of truth — same "契约先行" discipline as `api/auth`.
+ *
+ * THE SCOPE MODEL (normative — the registry implements EXACTLY this):
+ *
+ *  - A **scope** is a tenant boundary: `{id, name, createdAt}`. `id` is a slug (SCOPE_ID_REGEX).
+ *    The reserved id `"global"` (GLOBAL_SCOPE) is the DEFAULT scope: it always exists, is never
+ *    created via the API (ScopeCreateRequest rejects it) and is never deleted.
+ *  - **Membership** is per-scope: `{scopeId, principal, role}` where role is the existing 4-level
+ *    RBAC ladder (viewer < editor < publisher < admin). The SAME principal may be `editor` in scope A
+ *    and `viewer` in scope B.
+ *  - The **instance-level** `users.role` is unchanged and orthogonal: an instance `admin` administers
+ *    ALL scopes — inside any scope their effective role is always `"admin"` (see effectiveScopeRole).
+ *  - The **access JWT** gains an OPTIONAL `scope` claim (SCOPE_CLAIM) binding the token to its active
+ *    scope. A token WITHOUT the claim means `"global"` (tokenScopeOf) — full backward compatibility:
+ *    every pre-scope token keeps working, scoped to global. The refresh token is NOT scope-bound;
+ *    refresh re-mints per resolveTokenScope, and the client re-switches if it wants another scope.
+ *
+ * ENDPOINTS (paths in SCOPES_V1_PATHS / scopeMembersPath):
+ *
+ *   GET    /api/v1/scopes                → ScopesListResponse {scopes:[{id,name,role}]} — the CALLER's
+ *          scopes with their per-scope effective role (instance admin sees ALL scopes, role "admin").
+ *   POST   /api/v1/auth/scope            → switch active scope: ScopeSwitchRequest {scope} →
+ *          ScopeSwitchResponse {access_token, token_type:"Bearer", expires_in, scope, role}; errors are
+ *          OAuth-style OAuthErrorResponse (`invalid_request` = malformed / unknown scope shape,
+ *          `access_denied` = caller is not a member and not an instance admin — canSwitchScope).
+ *          Auth: a valid access token (any scope). Mints a NEW access token bound to `scope`; the
+ *          caller's refresh grant is untouched.
+ *   POST   /api/v1/scopes                → create a scope (instance admin only): ScopeCreateRequest
+ *          {id,name} → ScopeCreateResponse (the created Scope).
+ *   PUT    /api/v1/scopes/{id}/members   → upsert a member (instance admin only): ScopeMemberUpsertRequest
+ *          {principal, role} → ScopeMemberUpsertResponse (the stored membership row).
+ *   DELETE /api/v1/scopes/{id}/members   → remove a member (instance admin only): ScopeMemberDeleteRequest
+ *          {principal} → ScopeMemberDeleteResponse {ok:true} (idempotent — removing a non-member is 200).
+ *
+ * WIRE CASING: /api/v1/auth/scope is part of the OAuth face — snake_case on the wire (access_token,
+ * expires_in), matching `api/auth`. The /api/v1/scopes management face uses this package's camelCase
+ * (createdAt, scopeId) — it is a registry management API, not an OAuth endpoint.
+ *
+ * Pure zod contract + pure decision functions — zero IO, browser-safe. The decision functions
+ * (resolveTokenScope / canSwitchScope / effectiveScopeRole) are THE semantics: the registry
+ * implementation imports and calls these — it must not re-implement them.
+ */
+import { z } from "zod";
+import { USER_ROLES } from "../config-fns.js";
+import { ACCESS_TOKEN_TTL_SECONDS } from "./auth.js";
+// ── constants ────────────────────────────────────────────────────────────────────────────────────────────
+/** The reserved default scope. Always exists; every token without a `scope` claim lives here. */
+export const GLOBAL_SCOPE = "global";
+/** Scope ids that can never be created (or deleted) through the API. */
+export const RESERVED_SCOPE_IDS = [GLOBAL_SCOPE];
+/** Slug shape for scope ids: lowercase alphanumeric + inner dashes, 1–64 chars, no leading/trailing dash. */
+export const SCOPE_ID_REGEX = /^[a-z0-9](?:[a-z0-9-]{0,62}[a-z0-9])?$/;
+/** The scope endpoints, relative to the registry origin. `members` needs the scope id — use scopeMembersPath. */
+import { SCOPES_V1_PATHS } from "./wire.js";
+export { SCOPES_V1_PATHS, SCOPE_CLAIM } from "./wire.js"; // moved to the zero-dep wire subset (re-export = 字节兼容)
+/** `/api/v1/scopes/{id}/members` for PUT (upsert) and DELETE (remove). */
+export function scopeMembersPath(scopeId) {
+    return `${SCOPES_V1_PATHS.scopes}/${encodeURIComponent(scopeId)}/members`;
+}
+/** True for ids the API refuses to create/delete ("global"). */
+export function isReservedScopeId(id) {
+    return RESERVED_SCOPE_IDS.includes(id);
+}
+// ── core shapes ──────────────────────────────────────────────────────────────────────────────────────────
+/** A scope id on the wire — slug-validated. (The reserved "global" IS a valid ScopeId: it exists as an
+ *  entity everywhere except the create endpoint.) */
+export const ScopeId = z.string().regex(SCOPE_ID_REGEX, "scope id must be a slug: [a-z0-9-], 1-64 chars, no edge dash");
+/** The per-scope role ladder = the existing instance RBAC ladder (viewer < editor < publisher < admin). */
+export const ScopeRole = z.enum(USER_ROLES);
+/** The scope entity. */
+export const Scope = z
+    .object({
+    id: ScopeId,
+    /** Human display name (non-unique, non-secret). */
+    name: z.string().min(1).max(200),
+    /** Creation time, epoch MILLISECONDS. The reserved "global" scope reports its provisioning time. */
+    createdAt: z.number(),
+})
+    .passthrough();
+/** One membership row: `principal` holds `role` inside `scopeId`. Per-scope — the same principal may
+ *  hold different roles in different scopes. */
+export const ScopeMember = z
+    .object({
+    scopeId: ScopeId,
+    /** The user identity — same principal string the JWT `sub` / x-agent-principal pipeline uses. */
+    principal: z.string().min(1),
+    role: ScopeRole,
+})
+    .passthrough();
+// ── GET /api/v1/scopes ───────────────────────────────────────────────────────────────────────────────────
+/** One list entry: a scope the caller can act in, with the caller's EFFECTIVE role there
+ *  (effectiveScopeRole — instance admins list every scope with role "admin"). */
+export const ScopeListEntry = z
+    .object({
+    id: ScopeId,
+    name: z.string().min(1),
+    role: ScopeRole,
+})
+    .passthrough();
+export const ScopesListResponse = z.object({ scopes: z.array(ScopeListEntry) }).passthrough();
+// ── POST /api/v1/auth/scope (switch active scope — OAuth face, snake_case) ──────────────────────────────
+/** Request: the target scope. Errors: `invalid_request` (malformed), `access_denied` (not a member and
+ *  not an instance admin — canSwitchScope false). */
+export const ScopeSwitchRequest = z
+    .object({
+    scope: ScopeId,
+})
+    .passthrough();
+/** A fresh access token bound to the requested scope (`scope` claim = `scope` field below). The refresh
+ *  grant is untouched — this endpoint never returns a refresh_token. `role` = the caller's effective role
+ *  inside the new scope (effectiveScopeRole). */
+export const ScopeSwitchResponse = z
+    .object({
+    /** RS256 JWT with the `scope` claim set — verify per api/auth-bridge; VerifiedIdentity.scope carries it. */
+    access_token: z.string().min(1),
+    token_type: z.literal("Bearer"),
+    /** Access-token lifetime in seconds (ACCESS_TOKEN_TTL_SECONDS — same mint as api/auth). */
+    expires_in: z.number().int().positive(),
+    scope: ScopeId,
+    role: ScopeRole,
+})
+    .passthrough();
+/** Re-exported convenience: the switch endpoint mints through the SAME exit as api/auth (1h JWT). */
+export const SCOPE_SWITCH_TOKEN_TTL_SECONDS = ACCESS_TOKEN_TTL_SECONDS;
+// ── POST /api/v1/scopes (create — instance admin only) ──────────────────────────────────────────────────
+/** Reserved ids ("global") are rejected AT THE SCHEMA — the default scope pre-exists and is not creatable. */
+export const ScopeCreateRequest = z
+    .object({
+    id: ScopeId.refine((id) => !isReservedScopeId(id), { message: `"${GLOBAL_SCOPE}" is reserved` }),
+    name: z.string().min(1).max(200),
+})
+    .passthrough();
+/** The created scope, as stored. */
+export const ScopeCreateResponse = Scope;
+// ── PUT/DELETE /api/v1/scopes/{id}/members (membership writes — instance admin only) ────────────────────
+/** PUT body — upsert: sets `principal`'s role in the path scope, creating or replacing the row. */
+export const ScopeMemberUpsertRequest = z
+    .object({
+    principal: z.string().min(1),
+    role: ScopeRole,
+})
+    .passthrough();
+/** The stored membership row (scopeId echoes the path). */
+export const ScopeMemberUpsertResponse = ScopeMember;
+/** DELETE body — remove `principal` from the path scope. */
+export const ScopeMemberDeleteRequest = z
+    .object({
+    principal: z.string().min(1),
+})
+    .passthrough();
+/** Idempotent: `{ok:true}` whether or not the principal was a member (no membership disclosure beyond
+ *  what the admin caller already sees). */
+export const ScopeMemberDeleteResponse = z.object({ ok: z.literal(true) }).passthrough();
+/**
+ * THE instance-admin override rule, in one place:
+ *
+ *   **An instance `admin`'s effective role inside ANY scope is always `"admin"`** — regardless of whether
+ *   they hold a membership there or what that membership says. For everyone else the effective role is
+ *   exactly their membership role (`membershipRole`), and `undefined` when they have no membership.
+ *
+ * `instanceRole` is the instance-level users.role string; only the exact value `"admin"` triggers the
+ * override (publisher/editor/viewer at instance level grant NO cross-scope power).
+ */
+export function effectiveScopeRole(membershipRole, instanceRole) {
+    if (instanceRole === "admin")
+        return "admin";
+    return membershipRole;
+}
+/**
+ * THE token-minting scope decision — which scope (and role claim) a fresh access token binds to, given
+ * the principal's scope memberships and instance role. Deterministic; the registry (Node/Next) imports
+ * and calls this at every mint (device-flow grant AND refresh). NORMATIVE RULES (verbatim, 任务书拍定):
+ *
+ *   1. **唯一成员 scope** — exactly one membership → bind that scope, role = that membership's effective
+ *      role (effectiveScopeRole: instance admin ⇒ "admin").
+ *   2. **多个含 global** — multiple memberships, one of them "global" → bind "global", role = the global
+ *      membership's effective role.
+ *   3. **多个不含 global** — multiple memberships, none "global" → bind the scope whose id is FIRST in
+ *      lexicographic (UTF-16 code-unit) order — deterministic, no wall-clock/insertion-order dependence;
+ *      role = that membership's effective role.
+ *   4. **零成员** — no memberships → `{scope: "global", role: instanceRole}` (the instance role IS the
+ *      role claim, exactly as pre-scope tokens behaved — full backward compatibility).
+ *
+ * Duplicate scopeIds in the input: the entry that sorts first (by scopeId, then by role string) wins —
+ * callers should not pass duplicates, but the function stays deterministic if they do.
+ */
+export function resolveTokenScope(memberships, instanceRole) {
+    if (memberships.length === 0) {
+        return { scope: GLOBAL_SCOPE, role: instanceRole };
+    }
+    const sorted = [...memberships].sort((a, b) => a.scopeId < b.scopeId ? -1 : a.scopeId > b.scopeId ? 1 : a.role < b.role ? -1 : a.role > b.role ? 1 : 0);
+    if (sorted.length === 1) {
+        const only = sorted[0];
+        return { scope: only.scopeId, role: effectiveScopeRole(only.role, instanceRole) ?? only.role };
+    }
+    const global = sorted.find((m) => m.scopeId === GLOBAL_SCOPE);
+    const chosen = global ?? sorted[0];
+    return { scope: chosen.scopeId, role: effectiveScopeRole(chosen.role, instanceRole) ?? chosen.role };
+}
+/**
+ * THE scope-switch authorization decision (POST /api/v1/auth/scope): allowed ⇔ the caller is a MEMBER of
+ * `targetScope` (any role) OR an instance `admin` (who may enter any scope, including ones they are not
+ * a member of — their effective role there is "admin" per effectiveScopeRole). Everyone else →
+ * `access_denied`. Note: "global" gets NO special-case here — a multi-scope user without a global
+ * membership cannot switch to global (their default mint never lands there either, rule 3 above).
+ */
+export function canSwitchScope(memberships, instanceRole, targetScope) {
+    if (instanceRole === "admin")
+        return true;
+    return memberships.some((m) => m.scopeId === targetScope);
+}
+/**
+ * Read the active scope off verified JWT claims: a non-empty string `scope` claim, else GLOBAL_SCOPE.
+ * This is the ONE place the "missing claim = global" backward-compat rule lives — workers and the
+ * registry both call this instead of defaulting ad hoc.
+ */
+export function tokenScopeOf(claims) {
+    return typeof claims.scope === "string" && claims.scope.length > 0 ? claims.scope : GLOBAL_SCOPE;
+}

package/dist/api/wire.d.ts

@@ -0,0 +1,60 @@
+/**
+ * `api/wire` — the ZERO-DEPENDENCY wire subset of the auth/scopes contracts (server AI 接手首车,
+ * 2026-07-27,跨仓 candidate 落地):endpoint paths, protocol constants and PURE helper functions,
+ * with **no zod import** — so a zero-runtime-dependency client (e.g. `@sema-agent/sdk/registry`) can
+ * import these at RUNTIME instead of value-copying them behind a same-source anchor test.
+ *
+ * ⚠️ 拆分纪律:这里只放**纯**件(常量/纯函数/字面量类型)。zod schema 留在 `api/auth.ts` /
+ * `api/scopes.ts`(它们 re-export 本文件 ⇒ 既有导入面字节兼容,谁都不用改)。给本文件加东西前
+ * 自问:它 import 了任何东西吗?——答案必须是 no(test/wire-purity 打包门盯着)。
+ */
+/** 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];
+/** 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];
+/**
+ * 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;
+};
+export declare const SCOPES_V1_PATHS: {
+    /** GET (list) + POST (create). */
+    readonly scopes: "/api/v1/scopes";
+    /** POST — mint a new access token bound to another scope. */
+    readonly authScope: "/api/v1/auth/scope";
+};
+/** The JWT claim carrying the token's active scope. OPTIONAL — absent means GLOBAL_SCOPE (tokenScopeOf). */
+export declare const SCOPE_CLAIM = "scope";