@sema-agent/settings-schema 13.0.0 → 14.0.0

package/docs/openapi-auth.yaml

@@ -0,0 +1,357 @@
+# OpenAPI 3 contract for the registry /api/v1/auth/* face ONLY (REGISTRY-REBUILD-DESIGN §2, M1 shipped).
+# Source of truth for the shapes is src/api/auth.ts (zod) — this document mirrors it for docs/third-party
+# integration. When design §3's scripts/gen-openapi.mjs lands, this file becomes generated; until then it
+# is maintained by hand next to the zod module. Registry JWKS (the auth-bridge key source) is included
+# because the §5 bridge depends on it; the rest of the registry API is deliberately NOT documented here.
+openapi: 3.0.3
+info:
+  title: web-admin auth API
+  description: >
+    RFC 8628 device authorization grant + rotating refresh tokens + logout + browser consent,
+    plus the public JWKS a worker uses to verify the minted access JWTs (auth bridge, design §5).
+    Contract frozen in @sema-agent/settings-schema `api/auth` / `api/auth-bridge`.
+  version: 0.2.0
+paths:
+  /api/v1/auth/device/code:
+    post:
+      operationId: deviceCode
+      summary: Open an RFC 8628 device-authorization handshake
+      description: >
+        Unauthenticated by design — the client has no credentials yet. Returns the polling secret
+        (device_code, hash-persisted server-side, 15min TTL) and the human approval code (user_code).
+      requestBody:
+        required: false
+        content:
+          application/json:
+            schema: { $ref: "#/components/schemas/DeviceCodeRequest" }
+          application/x-www-form-urlencoded:
+            schema: { $ref: "#/components/schemas/DeviceCodeRequest" }
+      responses:
+        "200":
+          description: Handshake opened.
+          content:
+            application/json:
+              schema: { $ref: "#/components/schemas/DeviceCodeResponse" }
+        "400":
+          $ref: "#/components/responses/OAuthError"
+        "503":
+          description: SSO not configured on this registry (error=server_error).
+          content:
+            application/json:
+              schema: { $ref: "#/components/schemas/OAuthErrorResponse" }
+  /api/v1/auth/device/token:
+    post:
+      operationId: deviceToken
+      summary: Poll for tokens (RFC 8628 §3.4)
+      description: >
+        The client polls every `interval` seconds. 400 error codes while pending:
+        authorization_pending (keep polling) / slow_down (add 5s to the interval) /
+        expired_token (restart the flow) / access_denied (user denied — stop).
+        On approval the handshake is consumed atomically — the 200 is returned exactly once.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: { $ref: "#/components/schemas/DeviceTokenRequest" }
+          application/x-www-form-urlencoded:
+            schema: { $ref: "#/components/schemas/DeviceTokenRequest" }
+      responses:
+        "200":
+          description: Approved — tokens minted (once).
+          content:
+            application/json:
+              schema: { $ref: "#/components/schemas/TokenGrantResponse" }
+        "400":
+          $ref: "#/components/responses/OAuthError"
+        "503":
+          description: SSO not configured (error=server_error).
+          content:
+            application/json:
+              schema: { $ref: "#/components/schemas/OAuthErrorResponse" }
+  /api/v1/auth/token/refresh:
+    post:
+      operationId: tokenRefresh
+      summary: Rotate a refresh token (silent access-token renewal)
+      description: >
+        Strict single-use rotation — verify, revoke the old grant, issue a new grant + new access JWT.
+        A replayed or raced old refresh token answers invalid_grant. Clients MUST persist the returned
+        refresh_token before discarding the old one.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: { $ref: "#/components/schemas/TokenRefreshRequest" }
+          application/x-www-form-urlencoded:
+            schema: { $ref: "#/components/schemas/TokenRefreshRequest" }
+      responses:
+        "200":
+          description: Rotated — same shape as the device token success.
+          content:
+            application/json:
+              schema: { $ref: "#/components/schemas/TokenGrantResponse" }
+        "400":
+          description: invalid_grant (unknown/expired/revoked/replayed — no detail) or invalid_request.
+          content:
+            application/json:
+              schema: { $ref: "#/components/schemas/OAuthErrorResponse" }
+        "503":
+          description: SSO not configured (error=server_error).
+          content:
+            application/json:
+              schema: { $ref: "#/components/schemas/OAuthErrorResponse" }
+  /api/v1/auth/logout:
+    post:
+      operationId: logout
+      summary: Revoke a refresh grant (CLI logout)
+      description: >
+        Always 200 {ok:true} whether or not the token matched a live grant (RFC 7009 — no token-existence
+        disclosure). The already-minted access JWT stays valid until its 1h exp; revocation kills the
+        renewal path. 400 only for a malformed request.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: { $ref: "#/components/schemas/LogoutRequest" }
+          application/x-www-form-urlencoded:
+            schema: { $ref: "#/components/schemas/LogoutRequest" }
+      responses:
+        "200":
+          description: Revoked (or no-op).
+          content:
+            application/json:
+              schema: { $ref: "#/components/schemas/LogoutResponse" }
+        "400":
+          $ref: "#/components/responses/OAuthError"
+  /api/v1/auth/device/approve:
+    get:
+      operationId: deviceApproveLookup
+      summary: Consent-screen lookup (does this user_code name a live handshake?)
+      description: Session-cookie-gated (the /activate page). Does NOT approve.
+      security:
+        - sessionCookie: []
+      parameters:
+        - name: user_code
+          in: query
+          required: true
+          schema: { type: string }
+          description: Case-insensitive; dashes/spaces optional (normalized server-side to XXXX-XXXX).
+      responses:
+        "200":
+          description: Live handshake found.
+          content:
+            application/json:
+              schema: { $ref: "#/components/schemas/DeviceApproveLookupResponse" }
+        "400":
+          description: invalid_request (implausible code) or invalid_grant (unknown/expired).
+          content:
+            application/json:
+              schema: { $ref: "#/components/schemas/OAuthErrorResponse" }
+        "401":
+          description: Not signed in (no valid session cookie).
+    post:
+      operationId: deviceApprove
+      summary: Approve a pending handshake with the SESSION actor's identity
+      description: >
+        JSON-only content type (cross-site-request defence — a cross-site form cannot send
+        application/json without a CORS preflight). The approving principal/role come from the session
+        cookie exclusively, never from the body.
+      security:
+        - sessionCookie: []
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: { $ref: "#/components/schemas/DeviceApproveRequest" }
+      responses:
+        "200":
+          description: Approved — the polling client's next device/token call succeeds.
+          content:
+            application/json:
+              schema: { $ref: "#/components/schemas/DeviceApproveResponse" }
+        "400":
+          description: invalid_request (bad body/content-type) or invalid_grant (unknown/expired/already-approved).
+          content:
+            application/json:
+              schema: { $ref: "#/components/schemas/OAuthErrorResponse" }
+        "401":
+          description: Not signed in.
+  /api/auth/sso/jwks:
+    get:
+      operationId: jwks
+      summary: Public JWKS — the auth-bridge key source (design §5)
+      description: >
+        Public verification key(s) ONLY (RFC 7517 §5 — no auth). Workers verify registry-minted user
+        access JWTs against these keys per the auth-bridge rules (RS256 only, kid match, kid-miss single
+        forced refresh with ≥60s throttle, 24h offline grace then fail-closed). `{keys: []}` is a valid
+        response (SSO disabled) — every token then fails verification.
+      responses:
+        "200":
+          description: The key set (may be empty).
+          content:
+            application/json:
+              schema: { $ref: "#/components/schemas/WebAdminJwks" }
+components:
+  securitySchemes:
+    sessionCookie:
+      type: apiKey
+      in: cookie
+      name: session
+      description: The registry's existing HMAC-signed browser session (web login).
+  responses:
+    OAuthError:
+      description: RFC 6749/8628 error envelope — branch on `error`; `error_description` is diagnostic only.
+      content:
+        application/json:
+          schema: { $ref: "#/components/schemas/OAuthErrorResponse" }
+  schemas:
+    OAuthErrorResponse:
+      type: object
+      required: [error]
+      properties:
+        error:
+          type: string
+          enum:
+            - authorization_pending
+            - slow_down
+            - expired_token
+            - access_denied
+            - invalid_request
+            - unsupported_grant_type
+            - invalid_grant
+            - server_error
+        error_description:
+          type: string
+    DeviceCodeRequest:
+      type: object
+      properties:
+        client_name:
+          type: string
+          maxLength: 200
+          description: NON-secret display hint for the consent screen; falls back to the User-Agent.
+    DeviceCodeResponse:
+      type: object
+      required: [device_code, user_code, verification_uri, expires_in, interval]
+      properties:
+        device_code:
+          type: string
+          description: ≥256-bit opaque polling secret — returned once, hash-persisted server-side. Never log.
+        user_code:
+          type: string
+          description: Human approval code, "XXXX-XXXX" (base-20, no vowels/lookalikes).
+        verification_uri:
+          type: string
+          description: The /activate consent page.
+        verification_uri_complete:
+          type: string
+          description: verification_uri with ?user_code= pre-filled. OPTIONAL (RFC 8628 §3.2) — absent ⇒ show verification_uri + user_code; never an empty string.
+        expires_in:
+          type: integer
+          description: Seconds until the handshake expires (900).
+        interval:
+          type: integer
+          description: Minimum seconds between polls (5).
+    DeviceTokenRequest:
+      type: object
+      required: [grant_type, device_code]
+      properties:
+        grant_type:
+          type: string
+          enum: ["urn:ietf:params:oauth:grant-type:device_code"]
+        device_code:
+          type: string
+    TokenGrantResponse:
+      type: object
+      required: [access_token, refresh_token, token_type, expires_in]
+      properties:
+        access_token:
+          type: string
+          description: "RS256 JWT — claims: sub (principal), iss, iat, exp, role; optional aud. 1h TTL."
+        refresh_token:
+          type: string
+          description: NEW opaque rotating refresh token (30d sliding) — replaces the previous one.
+        token_type:
+          type: string
+          enum: [Bearer]
+        expires_in:
+          type: integer
+          description: Access-token lifetime in seconds (3600).
+    TokenRefreshRequest:
+      type: object
+      required: [refresh_token]
+      properties:
+        refresh_token:
+          type: string
+    LogoutRequest:
+      type: object
+      required: [refresh_token]
+      properties:
+        refresh_token:
+          type: string
+    LogoutResponse:
+      type: object
+      required: [ok]
+      properties:
+        ok:
+          type: boolean
+          enum: [true]
+    DeviceApproveLookupResponse:
+      type: object
+      required: [user_code, status, client, expires_at]
+      properties:
+        user_code:
+          type: string
+        status:
+          type: string
+          enum: [pending, approved, denied]
+          description: denied is contract-reserved (explicit deny button); M1 ships pending|approved.
+        client:
+          type: string
+          nullable: true
+          description: The client_name/User-Agent hint from device/code; null when none.
+        expires_at:
+          type: number
+          description: Handshake expiry, epoch MILLISECONDS.
+    DeviceApproveRequest:
+      type: object
+      required: [user_code]
+      properties:
+        user_code:
+          type: string
+          description: Case-insensitive; dashes/spaces optional.
+    DeviceApproveResponse:
+      type: object
+      required: [ok, user_code]
+      properties:
+        ok:
+          type: boolean
+          enum: [true]
+        user_code:
+          type: string
+    WebAdminJwks:
+      type: object
+      required: [keys]
+      properties:
+        keys:
+          type: array
+          items:
+            type: object
+            required: [kty, n, e, kid]
+            properties:
+              kty:
+                type: string
+                enum: [RSA]
+              n:
+                type: string
+                description: modulus, base64url
+              e:
+                type: string
+                description: exponent, base64url
+              kid:
+                type: string
+                description: RFC 7638 thumbprint — matches the JWT header kid.
+              use:
+                type: string
+                enum: [sig]
+              alg:
+                type: string
+                enum: [RS256]

package/docs/openapi-scopes.yaml

@@ -0,0 +1,281 @@
+# OpenAPI 3 contract for the registry multi-tenant SCOPE face ONLY (/api/v1/scopes* + /api/v1/auth/scope).
+# Source of truth for the shapes AND the decision semantics is src/api/scopes.ts (zod + pure functions:
+# resolveTokenScope / canSwitchScope / effectiveScopeRole / readTokenScope) — this document mirrors it for
+# docs/third-party integration, exactly like docs/openapi-auth.yaml mirrors src/api/auth.ts. Maintained by
+# hand next to the zod module until gen-openapi lands. The auth face lives in openapi-auth.yaml.
+openapi: 3.0.3
+info:
+  title: web-admin scopes API
+  description: >
+    Multi-tenant scopes: a scope is a tenant boundary {id,name,createdAt} with per-scope memberships
+    {scopeId,principal,role} (the existing viewer<editor<publisher<admin ladder — the same principal may
+    hold different roles in different scopes). The reserved scope "global" always exists and is the
+    default; every access JWT carries a `scope` claim, and a token without one is refused (401) — it is not read as "global".
+    Refresh tokens are NOT scope-bound (a refresh re-mints an access token with the claim).
+    Instance-level users.role is unchanged; an instance admin administers all scopes and their effective
+    role in any scope is always "admin". Contract frozen in @sema-agent/settings-schema `api/scopes`.
+  version: 0.3.0
+paths:
+  /api/v1/scopes:
+    get:
+      operationId: listScopes
+      summary: List the caller's scopes with their per-scope effective role
+      description: >
+        Auth: bearer access JWT (any scope). Returns the scopes the caller can act in, with the caller's
+        EFFECTIVE role in each (effectiveScopeRole — an instance admin sees ALL scopes with role "admin").
+      security:
+        - bearerJwt: []
+      responses:
+        "200":
+          description: The caller's scopes.
+          content:
+            application/json:
+              schema: { $ref: "#/components/schemas/ScopesListResponse" }
+        "401":
+          description: Missing/invalid bearer token.
+    post:
+      operationId: createScope
+      summary: Create a scope (instance admin only)
+      description: >
+        The reserved id "global" is rejected as invalid_request — the default scope pre-exists and is
+        neither creatable nor deletable. Duplicate id → invalid_request.
+      security:
+        - bearerJwt: []
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: { $ref: "#/components/schemas/ScopeCreateRequest" }
+      responses:
+        "200":
+          description: Created.
+          content:
+            application/json:
+              schema: { $ref: "#/components/schemas/Scope" }
+        "400":
+          $ref: "#/components/responses/OAuthError"
+        "401":
+          description: Missing/invalid bearer token.
+        "403":
+          description: Caller is not an instance admin (error=access_denied).
+          content:
+            application/json:
+              schema: { $ref: "#/components/schemas/OAuthErrorResponse" }
+  /api/v1/auth/scope:
+    post:
+      operationId: switchScope
+      summary: Mint a new access token bound to another scope
+      description: >
+        Auth: bearer access JWT (any scope). Allowed iff canSwitchScope — the caller is a MEMBER of the
+        target scope (any role) or an instance admin (any scope, effective role "admin"). "global" gets no
+        special case: a non-member non-admin cannot switch to it. Success mints a FRESH access JWT whose
+        `scope` claim = the requested scope and `role` claim = the caller's effective role there
+        (effectiveScopeRole); the refresh grant is untouched and NO refresh_token is returned — on refresh
+        the scope re-resolves via resolveTokenScope and the client re-switches if needed. Errors are
+        OAuth-style: invalid_request (malformed) / access_denied (not a member, not an admin).
+      security:
+        - bearerJwt: []
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: { $ref: "#/components/schemas/ScopeSwitchRequest" }
+      responses:
+        "200":
+          description: New scoped access token minted.
+          content:
+            application/json:
+              schema: { $ref: "#/components/schemas/ScopeSwitchResponse" }
+        "400":
+          $ref: "#/components/responses/OAuthError"
+        "401":
+          description: Missing/invalid bearer token.
+        "403":
+          description: Not a member of the target scope and not an instance admin (error=access_denied).
+          content:
+            application/json:
+              schema: { $ref: "#/components/schemas/OAuthErrorResponse" }
+  /api/v1/scopes/{id}/members:
+    parameters:
+      - name: id
+        in: path
+        required: true
+        schema: { $ref: "#/components/schemas/ScopeIdString" }
+        description: The scope id (slug).
+    put:
+      operationId: upsertScopeMember
+      summary: Upsert a member's role in a scope (instance admin only)
+      description: Creates or replaces the {scopeId, principal} membership row with the given role.
+      security:
+        - bearerJwt: []
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: { $ref: "#/components/schemas/ScopeMemberUpsertRequest" }
+      responses:
+        "200":
+          description: The stored membership row.
+          content:
+            application/json:
+              schema: { $ref: "#/components/schemas/ScopeMember" }
+        "400":
+          $ref: "#/components/responses/OAuthError"
+        "401":
+          description: Missing/invalid bearer token.
+        "403":
+          description: Caller is not an instance admin (error=access_denied).
+          content:
+            application/json:
+              schema: { $ref: "#/components/schemas/OAuthErrorResponse" }
+        "404":
+          description: Unknown scope id.
+    delete:
+      operationId: deleteScopeMember
+      summary: Remove a member from a scope (instance admin only)
+      description: Idempotent — removing a non-member still answers 200 {ok:true}.
+      security:
+        - bearerJwt: []
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: { $ref: "#/components/schemas/ScopeMemberDeleteRequest" }
+      responses:
+        "200":
+          description: Removed (or no-op).
+          content:
+            application/json:
+              schema: { $ref: "#/components/schemas/ScopeMemberDeleteResponse" }
+        "400":
+          $ref: "#/components/responses/OAuthError"
+        "401":
+          description: Missing/invalid bearer token.
+        "403":
+          description: Caller is not an instance admin (error=access_denied).
+          content:
+            application/json:
+              schema: { $ref: "#/components/schemas/OAuthErrorResponse" }
+        "404":
+          description: Unknown scope id.
+components:
+  securitySchemes:
+    bearerJwt:
+      type: http
+      scheme: bearer
+      bearerFormat: JWT
+      description: >
+        web-admin-minted RS256 access JWT (api/auth). Carries the `scope` claim (api/scopes); a token
+        without it is refused (readTokenScope ⇒ scope_claim_missing).
+  responses:
+    OAuthError:
+      description: OAuth-style error envelope — branch on `error`; `error_description` is diagnostic only.
+      content:
+        application/json:
+          schema: { $ref: "#/components/schemas/OAuthErrorResponse" }
+  schemas:
+    OAuthErrorResponse:
+      type: object
+      required: [error]
+      properties:
+        error:
+          type: string
+          enum:
+            - invalid_request
+            - access_denied
+            - invalid_grant
+            - server_error
+        error_description:
+          type: string
+    ScopeIdString:
+      type: string
+      pattern: "^[a-z0-9](?:[a-z0-9-]{0,62}[a-z0-9])?$"
+      description: Slug, 1-64 chars, lowercase alnum + inner dashes. "global" is the reserved default scope.
+    ScopeRole:
+      type: string
+      enum: [viewer, editor, publisher, admin]
+      description: The existing 4-level RBAC ladder, applied PER SCOPE.
+    Scope:
+      type: object
+      required: [id, name, createdAt]
+      properties:
+        id: { $ref: "#/components/schemas/ScopeIdString" }
+        name:
+          type: string
+          maxLength: 200
+        createdAt:
+          type: number
+          description: Creation time, epoch milliseconds.
+    ScopeMember:
+      type: object
+      required: [scopeId, principal, role]
+      properties:
+        scopeId: { $ref: "#/components/schemas/ScopeIdString" }
+        principal:
+          type: string
+          description: Same principal string as the JWT sub / x-agent-principal pipeline.
+        role: { $ref: "#/components/schemas/ScopeRole" }
+    ScopesListResponse:
+      type: object
+      required: [scopes]
+      properties:
+        scopes:
+          type: array
+          items:
+            type: object
+            required: [id, name, role]
+            properties:
+              id: { $ref: "#/components/schemas/ScopeIdString" }
+              name: { type: string }
+              role:
+                allOf: [{ $ref: "#/components/schemas/ScopeRole" }]
+                description: The CALLER's effective role in this scope (instance admin ⇒ "admin").
+    ScopeSwitchRequest:
+      type: object
+      required: [scope]
+      properties:
+        scope: { $ref: "#/components/schemas/ScopeIdString" }
+    ScopeSwitchResponse:
+      type: object
+      required: [access_token, token_type, expires_in, scope, role]
+      properties:
+        access_token:
+          type: string
+          description: Fresh RS256 JWT with the `scope` claim set. Never log.
+        token_type:
+          type: string
+          enum: ["Bearer"]
+        expires_in:
+          type: integer
+          description: Access-token lifetime in seconds (3600 — same mint as api/auth).
+        scope: { $ref: "#/components/schemas/ScopeIdString" }
+        role: { $ref: "#/components/schemas/ScopeRole" }
+    ScopeCreateRequest:
+      type: object
+      required: [id, name]
+      properties:
+        id:
+          allOf: [{ $ref: "#/components/schemas/ScopeIdString" }]
+          description: Must not be a reserved id ("global").
+        name:
+          type: string
+          minLength: 1
+          maxLength: 200
+    ScopeMemberUpsertRequest:
+      type: object
+      required: [principal, role]
+      properties:
+        principal: { type: string }
+        role: { $ref: "#/components/schemas/ScopeRole" }
+    ScopeMemberDeleteRequest:
+      type: object
+      required: [principal]
+      properties:
+        principal: { type: string }
+    ScopeMemberDeleteResponse:
+      type: object
+      required: [ok]
+      properties:
+        ok:
+          type: boolean
+          enum: [true]