@willyim/idp 0.1.1 → 0.3.0

package/dist/src/schemas/operations.js

@@ -0,0 +1,213 @@
+/**
+ * Every operation the management API exposes, in one table.
+ *
+ * Three things read it: `buildOpenApiDocument` (in `./openapi.ts`) turns it
+ * into the published document, `api.ts` uses it to type its `request()` and to
+ * parse what comes back, and `apps/idp` validates request bodies with the same
+ * `input` schemas. Adding an endpoint means adding a row here; nothing else
+ * needs to learn about it.
+ */
+import { z } from "zod";
+import { AdminKeyCreatedSchema, AdminKeyListSchema, ApiKeyCreatedSchema, ApiKeyListSchema, ApplicationCreatedSchema, ApplicationListSchema, ApplicationSchema, AppPermissionsSchema, AuditListSchema, ClientSecretSchema, CreateAdminKeyInput, CreateApiKeyInput, CreateApplicationInput, CreateUserApiKeyInput, CreateWorkspaceInput, InviteMemberInput, InviteMemberResult, MemberListSchema, OkSchema, SetAppPermissionsInput, UpdateApplicationInput, UpdateMemberInput, UserApiKeyCreatedSchema, UserApiKeyListSchema, UserApiKeyValidationSchema, UserListSchema, ValidateUserApiKeyInput, WorkspaceCreatedSchema, WorkspaceListSchema, } from "./index.js";
+const APP_PARAM = { app: "Application key (oauth_client.metadata.app)." };
+const CLIENT_PARAM = { clientId: "OAuth client id of the application." };
+export const operations = {
+    "get /api/v1/applications": {
+        summary: "List registered applications",
+        successCode: "200",
+        success: ApplicationListSchema,
+    },
+    "post /api/v1/applications": {
+        summary: "Register an application (client secret returned once)",
+        description: "Requires the superadmin token. Creating an application is an IdP-level act — there is no app to scope a permission to yet.",
+        input: CreateApplicationInput,
+        successCode: "201",
+        success: ApplicationCreatedSchema,
+    },
+    "get /api/v1/applications/{clientId}": {
+        summary: "Get one application",
+        permission: "app:read",
+        params: CLIENT_PARAM,
+        notFound: "No application with that client id",
+        successCode: "200",
+        success: ApplicationSchema,
+    },
+    "patch /api/v1/applications/{clientId}": {
+        summary: "Update an application",
+        permission: "app:update",
+        params: CLIENT_PARAM,
+        notFound: "No application with that client id",
+        input: UpdateApplicationInput,
+        successCode: "200",
+        success: ApplicationSchema,
+    },
+    "delete /api/v1/applications/{clientId}": {
+        summary: "Deregister an application",
+        permission: "app:delete",
+        params: CLIENT_PARAM,
+        notFound: "No application with that client id",
+        successCode: "200",
+        success: OkSchema,
+    },
+    "post /api/v1/applications/{clientId}/rotate-secret": {
+        summary: "Rotate the client secret (returned once; the old one stops working)",
+        permission: "app:update",
+        params: CLIENT_PARAM,
+        notFound: "No application with that client id",
+        successCode: "200",
+        success: ClientSecretSchema,
+    },
+    "put /api/v1/apps/{app}/permissions": {
+        summary: "Replace the app's product-permission catalog",
+        permission: "app:update",
+        params: APP_PARAM,
+        notFound: "No application with that app key",
+        input: SetAppPermissionsInput,
+        successCode: "200",
+        success: AppPermissionsSchema,
+    },
+    "get /api/v1/apps/{app}/keys": {
+        summary: "List scoped management API keys (never the hashes)",
+        permission: "apikey:read",
+        params: APP_PARAM,
+        successCode: "200",
+        success: ApiKeyListSchema,
+    },
+    "post /api/v1/apps/{app}/keys": {
+        summary: "Mint a scoped management API key (plaintext returned once)",
+        description: "Requires `apikey:create` on the path app (or the superadmin token). The requested permissions must be a subset of the caller's own, otherwise 403 `permissions_exceed_caller` — without that rule any key holding `apikey:create` could mint itself a more powerful successor.",
+        permission: "apikey:create",
+        params: APP_PARAM,
+        input: CreateApiKeyInput,
+        successCode: "201",
+        success: ApiKeyCreatedSchema,
+    },
+    "delete /api/v1/apps/{app}/keys/{id}": {
+        summary: "Revoke a scoped management API key (idempotent)",
+        permission: "apikey:revoke",
+        params: APP_PARAM,
+        notFound: "No key with that id on this app",
+        successCode: "200",
+        success: OkSchema,
+    },
+    "get /api/v1/admin-keys": {
+        summary: "List IdP-level admin keys (never the hashes)",
+        description: "Requires the superadmin token or an admin key. Admin keys are `api_key` rows with no application scope, so they hold every permission on every app.",
+        successCode: "200",
+        success: AdminKeyListSchema,
+    },
+    "post /api/v1/admin-keys": {
+        summary: "Mint an IdP-level admin key (plaintext returned once)",
+        description: "Requires the superadmin token or an admin key. Mint one per agent: unlike the static ADMIN_API_TOKEN, an admin key has a name, an optional expiry, a revoke switch, and its own `adminkey:<id>` identity in the audit log.",
+        input: CreateAdminKeyInput,
+        successCode: "201",
+        success: AdminKeyCreatedSchema,
+    },
+    "delete /api/v1/admin-keys/{id}": {
+        summary: "Revoke an IdP-level admin key (idempotent)",
+        description: "A key may revoke itself — an agent cleaning up after itself is legitimate — after which its next request is simply unauthorized.",
+        params: { id: "Admin key id." },
+        notFound: "No admin key with that id",
+        successCode: "200",
+        success: OkSchema,
+    },
+    "get /api/v1/users": {
+        summary: "List users",
+        successCode: "200",
+        success: UserListSchema,
+    },
+    "get /api/v1/workspaces": {
+        summary: "List workspaces",
+        successCode: "200",
+        success: WorkspaceListSchema,
+    },
+    "get /api/v1/apps/{app}/members": {
+        summary: "List app members",
+        permission: "member:read",
+        params: APP_PARAM,
+        successCode: "200",
+        success: MemberListSchema,
+    },
+    "post /api/v1/apps/{app}/members": {
+        summary: "Add or invite a member",
+        permission: "member:invite",
+        params: APP_PARAM,
+        input: InviteMemberInput,
+        successCode: "201",
+        success: InviteMemberResult,
+    },
+    "patch /api/v1/apps/{app}/members/{userId}": {
+        summary: "Update a member's role + permissions",
+        permission: "member:manage",
+        params: APP_PARAM,
+        input: UpdateMemberInput,
+        successCode: "200",
+        success: OkSchema,
+    },
+    "delete /api/v1/apps/{app}/members/{userId}": {
+        summary: "Remove a member",
+        permission: "member:manage",
+        params: APP_PARAM,
+        successCode: "200",
+        success: OkSchema,
+    },
+    "get /api/v1/apps/{app}/workspaces": {
+        summary: "List app workspaces",
+        permission: "workspace:read",
+        params: APP_PARAM,
+        successCode: "200",
+        success: WorkspaceListSchema,
+    },
+    "post /api/v1/apps/{app}/workspaces": {
+        summary: "Create a workspace",
+        permission: "workspace:create",
+        params: APP_PARAM,
+        input: CreateWorkspaceInput,
+        successCode: "201",
+        success: WorkspaceCreatedSchema,
+    },
+    "get /api/v1/apps/{app}/user-keys": {
+        summary: "List end-user API keys",
+        permission: "userkey:read",
+        params: APP_PARAM,
+        query: [
+            { name: "userId", description: "Only keys owned by this user." },
+            { name: "workspaceId", description: "Only keys bound to this workspace." },
+        ],
+        successCode: "200",
+        success: UserApiKeyListSchema,
+    },
+    "post /api/v1/apps/{app}/user-keys": {
+        summary: "Mint an end-user API key (plaintext returned once)",
+        permission: "userkey:create",
+        params: APP_PARAM,
+        input: CreateUserApiKeyInput,
+        successCode: "201",
+        success: UserApiKeyCreatedSchema,
+    },
+    "post /api/v1/apps/{app}/user-keys/validate": {
+        summary: "Validate a presented end-user key (200 + valid discriminator)",
+        permission: "userkey:validate",
+        params: APP_PARAM,
+        input: ValidateUserApiKeyInput,
+        successCode: "200",
+        success: UserApiKeyValidationSchema,
+    },
+    "delete /api/v1/apps/{app}/user-keys/{id}": {
+        summary: "Revoke an end-user API key (idempotent)",
+        permission: "userkey:revoke",
+        params: APP_PARAM,
+        successCode: "200",
+        success: OkSchema,
+    },
+    "get /api/v1/apps/{app}/audit": {
+        summary: "List recent audit entries",
+        permission: "audit:read",
+        params: APP_PARAM,
+        successCode: "200",
+        success: AuditListSchema,
+    },
+};
+export function lookup(method, path) {
+    return operations[`${method.toLowerCase()} ${path}`];
+}

package/dist/src/session.d.ts

@@ -68,14 +68,28 @@ export type Idp = ReturnType<typeof createIdp>;
 export declare function createIdp(options: IdpOptions): {
     /** The Layer 0 client, for anything the session layer doesn't wrap. */
     client: {
-        discover: () => Promise<import("./client.js").Discovery>;
+        discover: () => Promise<import("./wire.js").Discovery>;
         authorizationUrl(input: import("./client.js").AuthorizationUrlInput): Promise<string>;
         exchangeCode(input: {
             code: string;
             redirectUri: string;
             codeVerifier: string;
-        }): Promise<import("./client.js").Tokens>;
-        refresh(refreshToken: string): Promise<import("./client.js").Tokens>;
+        }): Promise<{
+            accessToken: string;
+            tokenType: string;
+            expiresIn: number | null;
+            refreshToken: string | null;
+            idToken: string | null;
+            scope: string | null;
+        }>;
+        refresh(refreshToken: string): Promise<{
+            accessToken: string;
+            tokenType: string;
+            expiresIn: number | null;
+            refreshToken: string | null;
+            idToken: string | null;
+            scope: string | null;
+        }>;
         userinfo(accessToken: string): Promise<Claims>;
         logoutUrl(input: {
             idToken?: string | null;

package/dist/src/session.d.ts.map

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

package/dist/src/session.js

@@ -8,6 +8,7 @@
  * call doubles as a liveness ping — it is how a revocation at the IdP reaches
  * the app, in minutes rather than in session-lengths.
  */
+import { z } from "zod";
 import { grants } from "./claims.js";
 import { createIdpClient, createPkce, IdpError, } from "./client.js";
 import { clearCookie, readCookie, serializeCookie } from "./cookie.js";
@@ -16,6 +17,16 @@ import { parseDuration } from "./duration.js";
 export const DEFAULT_SESSION_COOKIE = "idp_session";
 /** How long the login handshake may take before its state cookie is stale. */
 const STATE_COOKIE_MAX_AGE_MS = 10 * 60_000;
+/**
+ * What rides in the login state cookie. HMAC-signed, so tampering is caught
+ * before this ever parses — the schema is here to catch a cookie left over
+ * from an older version of the SDK, not an attacker.
+ */
+const StatePayloadSchema = z.object({
+    state: z.string().min(1),
+    codeVerifier: z.string().min(1),
+    next: z.string().optional(),
+});
 export function createIdp(options) {
     const client = createIdpClient(options);
     const store = options.sessions;
@@ -255,7 +266,7 @@ export function createIdp(options) {
                 throw new IdpError("login state cookie is missing or invalid", 400);
             let payload;
             try {
-                payload = JSON.parse(base64urlDecodeString(raw));
+                payload = StatePayloadSchema.parse(JSON.parse(base64urlDecodeString(raw)));
             }
             catch {
                 throw new IdpError("login state cookie is malformed", 400);

package/dist/src/user-keys.d.ts

@@ -0,0 +1,124 @@
+/**
+ * End-user API keys, from the consuming app's side.
+ *
+ * The IdP is the key store: an app mints, lists, revokes and validates `wak_…`
+ * keys through the management API, authenticated with its own scoped `wim_…`
+ * key, and never persists a plaintext token or a hash of one. This module is
+ * the sugar over those four calls, plus the two things every consumer would
+ * otherwise write badly by hand:
+ *
+ *  - a validation cache. `validate` is a network round trip, and API keys
+ *    arrive on the request-per-request hot path. Results are cached by digest
+ *    of the token, with a short TTL, and concurrent validations of the same
+ *    token share one in-flight request. The cost is revocation lag bounded by
+ *    `cache.ttlMs` — pick it deliberately, and call `forget` after a revoke you
+ *    performed yourself.
+ *  - `authenticate`, which reads the bearer token off a `Request`, validates it
+ *    and checks required scopes, returning a discriminated result rather than
+ *    throwing, so the caller decides what a 401 looks like.
+ *
+ * Only for *secret* credentials. A public write key embedded in a page (an
+ * analytics ingest token, say) identifies a site rather than a user, cannot be
+ * kept secret, and must not pay a round trip per hit — keep those in the app's
+ * own table.
+ */
+import type { z } from "zod";
+import { type ManagementApiOptions } from "./api.js";
+import type { CreateUserApiKeyInput, UserApiKeyCreatedSchema, UserApiKeySchema, UserApiKeyValidationSchema } from "./schemas/index.js";
+type CreateBody = z.input<typeof CreateUserApiKeyInput>;
+/** One key as the IdP reports it. Never includes the token or its hash. */
+export type UserApiKey = z.output<typeof UserApiKeySchema>;
+/** What `create` hands back. `token` is the only time the plaintext exists. */
+export type MintedUserApiKey = z.output<typeof UserApiKeyCreatedSchema>;
+/** A validation verdict. A miss is data, not an error — hence `valid: false`. */
+export type UserKeyValidation = z.output<typeof UserApiKeyValidationSchema>;
+/** The `valid: true` half, i.e. an authenticated key. */
+export type AuthenticatedKey = Extract<UserKeyValidation, {
+    valid: true;
+}>;
+export type UserKeyCacheOptions = {
+    /** How long a `valid: true` verdict is reused. Default 60s. */
+    ttlMs?: number;
+    /** How long a `valid: false` verdict is reused. Default 10s. */
+    missTtlMs?: number;
+    /** Entry ceiling before the oldest are dropped. Default 1000. */
+    max?: number;
+};
+export type UserKeysOptions = ManagementApiOptions & {
+    /** The app key these keys belong to — `oauth_client.metadata.app`. */
+    app: string;
+    /** `false` disables caching entirely (every validate is a round trip). */
+    cache?: UserKeyCacheOptions | false;
+    /** Clock seam, for tests. */
+    now?: () => number;
+};
+export type ListFilter = {
+    userId?: string;
+    workspaceId?: string;
+    signal?: AbortSignal;
+};
+export type CreateUserApiKeyInput = CreateBody & {
+    signal?: AbortSignal;
+};
+export type AuthenticateOptions = {
+    /** Every scope listed must be present on the key. */
+    scopes?: string[];
+    signal?: AbortSignal;
+};
+export type AuthenticateResult = {
+    ok: true;
+    key: AuthenticatedKey;
+} | {
+    ok: false;
+    status: 401 | 403;
+    reason: "missing" | "not_found" | "revoked" | "expired" | "insufficient_scope";
+    /** The scopes that were required but absent, when `insufficient_scope`. */
+    missing?: string[];
+};
+/**
+ * Reads a presented key off a request: `Authorization: Bearer …` first, then
+ * `X-API-Key`. Returns null when neither is present, so "no credential" stays
+ * distinguishable from "bad credential".
+ */
+export declare function readApiKey(request: {
+    headers: Headers;
+}): string | null;
+export declare function createUserKeys(options: UserKeysOptions): {
+    validate: (token: string, init?: {
+        signal?: AbortSignal;
+        fresh?: boolean;
+    }) => Promise<UserKeyValidation>;
+    /** The keys this app has minted, newest first. Optionally filtered. */
+    list(filter?: ListFilter): Promise<UserApiKey[]>;
+    /**
+     * Mints a key for one of the app's users. The returned `token` is the only
+     * copy — show it once and forget it. Scopes must come from the app's
+     * declared product permission catalog; unknown ones are a 422, not a
+     * silent drop.
+     */
+    create(input: CreateUserApiKeyInput): Promise<MintedUserApiKey>;
+    /**
+     * Revokes a key by id (idempotent). Cached verdicts for *other* tokens are
+     * untouched; this app never saw the revoked plaintext, so the entry for it
+     * can only expire on its own TTL. Call `forget(token)` instead when the
+     * plaintext is in hand.
+     */
+    revoke(id: string, init?: {
+        signal?: AbortSignal;
+    }): Promise<{
+        ok: true;
+    }>;
+    /**
+     * The whole check in one call: read the credential off the request,
+     * validate it, and confirm every required scope. Returns a result rather
+     * than throwing, so the caller owns the response shape.
+     */
+    authenticate(request: {
+        headers: Headers;
+    }, init?: AuthenticateOptions): Promise<AuthenticateResult>;
+    /** Drops one token's cached verdict, or the whole cache when called bare. */
+    forget(token?: string): Promise<void>;
+};
+export type UserKeys = ReturnType<typeof createUserKeys>;
+export {};
+//# sourceMappingURL=user-keys.d.ts.map

package/dist/src/user-keys.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"user-keys.d.ts","sourceRoot":"","sources":["../../src/user-keys.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAE5B,OAAO,EAAuB,KAAK,oBAAoB,EAAE,MAAM,UAAU,CAAA;AAEzE,OAAO,KAAK,EACV,qBAAqB,EACrB,uBAAuB,EACvB,gBAAgB,EAChB,0BAA0B,EAC3B,MAAM,oBAAoB,CAAA;AAE3B,KAAK,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAA;AAEvD,2EAA2E;AAC3E,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,gBAAgB,CAAC,CAAA;AAE1D,+EAA+E;AAC/E,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,uBAAuB,CAAC,CAAA;AAEvE,iFAAiF;AACjF,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,0BAA0B,CAAC,CAAA;AAE3E,yDAAyD;AACzD,MAAM,MAAM,gBAAgB,GAAG,OAAO,CAAC,iBAAiB,EAAE;IAAE,KAAK,EAAE,IAAI,CAAA;CAAE,CAAC,CAAA;AAE1E,MAAM,MAAM,mBAAmB,GAAG;IAChC,+DAA+D;IAC/D,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,gEAAgE;IAChE,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,iEAAiE;IACjE,GAAG,CAAC,EAAE,MAAM,CAAA;CACb,CAAA;AAED,MAAM,MAAM,eAAe,GAAG,oBAAoB,GAAG;IACnD,sEAAsE;IACtE,GAAG,EAAE,MAAM,CAAA;IACX,0EAA0E;IAC1E,KAAK,CAAC,EAAE,mBAAmB,GAAG,KAAK,CAAA;IACnC,6BAA6B;IAC7B,GAAG,CAAC,EAAE,MAAM,MAAM,CAAA;CACnB,CAAA;AAED,MAAM,MAAM,UAAU,GAAG;IACvB,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,MAAM,CAAC,EAAE,WAAW,CAAA;CACrB,CAAA;AAED,MAAM,MAAM,qBAAqB,GAAG,UAAU,GAAG;IAAE,MAAM,CAAC,EAAE,WAAW,CAAA;CAAE,CAAA;AAEzE,MAAM,MAAM,mBAAmB,GAAG;IAChC,qDAAqD;IACrD,MAAM,CAAC,EAAE,MAAM,EAAE,CAAA;IACjB,MAAM,CAAC,EAAE,WAAW,CAAA;CACrB,CAAA;AAED,MAAM,MAAM,kBAAkB,GAC1B;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,GAAG,EAAE,gBAAgB,CAAA;CAAE,GACnC;IACE,EAAE,EAAE,KAAK,CAAA;IACT,MAAM,EAAE,GAAG,GAAG,GAAG,CAAA;IACjB,MAAM,EAAE,SAAS,GAAG,WAAW,GAAG,SAAS,GAAG,SAAS,GAAG,oBAAoB,CAAA;IAC9E,2EAA2E;IAC3E,OAAO,CAAC,EAAE,MAAM,EAAE,CAAA;CACnB,CAAA;AAML;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE;IAAE,OAAO,EAAE,OAAO,CAAA;CAAE,GAAG,MAAM,GAAG,IAAI,CAQvE;AAID,wBAAgB,cAAc,CAAC,OAAO,EAAE,eAAe;sBAyC5C,MAAM,SACP;QAAE,MAAM,CAAC,EAAE,WAAW,CAAC;QAAC,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE,KAC9C,OAAO,CAAC,iBAAiB,CAAC;IA8B3B,uEAAuE;kBACpD,UAAU,GAAQ,OAAO,CAAC,UAAU,EAAE,CAAC;IAS1D;;;;;OAKG;kBACiB,qBAAqB,GAAG,OAAO,CAAC,gBAAgB,CAAC;IASrE;;;;;OAKG;eACc,MAAM,SAAQ;QAAE,MAAM,CAAC,EAAE,WAAW,CAAA;KAAE,GAAQ,OAAO,CAAC;QAAE,EAAE,EAAE,IAAI,CAAA;KAAE,CAAC;IAOpF;;;;OAIG;0BAEQ;QAAE,OAAO,EAAE,OAAO,CAAA;KAAE,SACvB,mBAAmB,GACxB,OAAO,CAAC,kBAAkB,CAAC;IAe9B,6EAA6E;mBACxD,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;EAQ9C;AAED,MAAM,MAAM,QAAQ,GAAG,UAAU,CAAC,OAAO,cAAc,CAAC,CAAA"}

package/dist/src/user-keys.js

@@ -0,0 +1,174 @@
+/**
+ * End-user API keys, from the consuming app's side.
+ *
+ * The IdP is the key store: an app mints, lists, revokes and validates `wak_…`
+ * keys through the management API, authenticated with its own scoped `wim_…`
+ * key, and never persists a plaintext token or a hash of one. This module is
+ * the sugar over those four calls, plus the two things every consumer would
+ * otherwise write badly by hand:
+ *
+ *  - a validation cache. `validate` is a network round trip, and API keys
+ *    arrive on the request-per-request hot path. Results are cached by digest
+ *    of the token, with a short TTL, and concurrent validations of the same
+ *    token share one in-flight request. The cost is revocation lag bounded by
+ *    `cache.ttlMs` — pick it deliberately, and call `forget` after a revoke you
+ *    performed yourself.
+ *  - `authenticate`, which reads the bearer token off a `Request`, validates it
+ *    and checks required scopes, returning a discriminated result rather than
+ *    throwing, so the caller decides what a 401 looks like.
+ *
+ * Only for *secret* credentials. A public write key embedded in a page (an
+ * analytics ingest token, say) identifies a site rather than a user, cannot be
+ * kept secret, and must not pay a round trip per hit — keep those in the app's
+ * own table.
+ */
+import { createManagementApi } from "./api.js";
+import { sha256Base64url } from "./crypto.js";
+const DEFAULT_TTL_MS = 60_000;
+const DEFAULT_MISS_TTL_MS = 10_000;
+const DEFAULT_MAX = 1000;
+/**
+ * Reads a presented key off a request: `Authorization: Bearer …` first, then
+ * `X-API-Key`. Returns null when neither is present, so "no credential" stays
+ * distinguishable from "bad credential".
+ */
+export function readApiKey(request) {
+    const authorization = request.headers.get("authorization");
+    if (authorization) {
+        const [scheme, ...rest] = authorization.split(" ");
+        const value = rest.join(" ").trim();
+        if (scheme?.toLowerCase() === "bearer" && value)
+            return value;
+    }
+    return request.headers.get("x-api-key")?.trim() || null;
+}
+export function createUserKeys(options) {
+    const api = createManagementApi(options);
+    const app = options.app;
+    const now = options.now ?? (() => Date.now());
+    const caching = options.cache !== false;
+    const ttlMs = (options.cache || {}).ttlMs ?? DEFAULT_TTL_MS;
+    const missTtlMs = (options.cache || {}).missTtlMs ?? DEFAULT_MISS_TTL_MS;
+    const max = (options.cache || {}).max ?? DEFAULT_MAX;
+    // Keyed by digest, never by the token itself: a heap dump or a logged Map
+    // then leaks nothing usable. Insertion-ordered, so the oldest entry is the
+    // first key — good enough eviction for a cache this size.
+    const cache = new Map();
+    const inFlight = new Map();
+    const digest = (token) => sha256Base64url(`user-key:${app}:${token}`);
+    function remember(key, verdict) {
+        if (!caching)
+            return;
+        if (cache.size >= max) {
+            const oldest = cache.keys().next();
+            if (!oldest.done)
+                cache.delete(oldest.value);
+        }
+        cache.set(key, { verdict, expiresAt: now() + (verdict.valid ? ttlMs : missTtlMs) });
+    }
+    async function fetchVerdict(token, signal) {
+        return api.request("post", "/api/v1/apps/{app}/user-keys/validate", {
+            params: { app },
+            body: { token },
+            signal,
+        });
+    }
+    /**
+     * Validates a presented token. Served from cache when fresh; concurrent
+     * callers presenting the same token share one round trip. `fresh: true`
+     * bypasses the cache for that call and reseeds it.
+     */
+    async function validate(token, init = {}) {
+        if (!token)
+            return { valid: false, reason: "not_found" };
+        const key = await digest(token);
+        if (!init.fresh && caching) {
+            const hit = cache.get(key);
+            if (hit && hit.expiresAt > now())
+                return hit.verdict;
+            if (hit)
+                cache.delete(key);
+            const pending = inFlight.get(key);
+            if (pending)
+                return pending;
+        }
+        const request = fetchVerdict(token, init.signal)
+            .then((verdict) => {
+            remember(key, verdict);
+            return verdict;
+        })
+            .finally(() => {
+            inFlight.delete(key);
+        });
+        // A failed round trip must not be cached — an IdP blip would otherwise
+        // lock every caller out for the whole TTL.
+        if (caching)
+            inFlight.set(key, request);
+        return request;
+    }
+    return {
+        validate,
+        /** The keys this app has minted, newest first. Optionally filtered. */
+        async list(filter = {}) {
+            const { keys } = await api.request("get", "/api/v1/apps/{app}/user-keys", {
+                params: { app },
+                query: { userId: filter.userId, workspaceId: filter.workspaceId },
+                signal: filter.signal,
+            });
+            return keys;
+        },
+        /**
+         * Mints a key for one of the app's users. The returned `token` is the only
+         * copy — show it once and forget it. Scopes must come from the app's
+         * declared product permission catalog; unknown ones are a 422, not a
+         * silent drop.
+         */
+        async create(input) {
+            const { signal, ...body } = input;
+            return api.request("post", "/api/v1/apps/{app}/user-keys", {
+                params: { app },
+                body,
+                signal,
+            });
+        },
+        /**
+         * Revokes a key by id (idempotent). Cached verdicts for *other* tokens are
+         * untouched; this app never saw the revoked plaintext, so the entry for it
+         * can only expire on its own TTL. Call `forget(token)` instead when the
+         * plaintext is in hand.
+         */
+        async revoke(id, init = {}) {
+            return api.request("delete", "/api/v1/apps/{app}/user-keys/{id}", {
+                params: { app, id },
+                signal: init.signal,
+            });
+        },
+        /**
+         * The whole check in one call: read the credential off the request,
+         * validate it, and confirm every required scope. Returns a result rather
+         * than throwing, so the caller owns the response shape.
+         */
+        async authenticate(request, init = {}) {
+            const token = readApiKey(request);
+            if (!token)
+                return { ok: false, status: 401, reason: "missing" };
+            const verdict = await validate(token, { signal: init.signal });
+            if (!verdict.valid)
+                return { ok: false, status: 401, reason: verdict.reason };
+            const required = init.scopes ?? [];
+            const missing = required.filter((scope) => !verdict.scopes.includes(scope));
+            if (missing.length) {
+                return { ok: false, status: 403, reason: "insufficient_scope", missing };
+            }
+            return { ok: true, key: verdict };
+        },
+        /** Drops one token's cached verdict, or the whole cache when called bare. */
+        async forget(token) {
+            if (token === undefined) {
+                cache.clear();
+                return;
+            }
+            cache.delete(await digest(token));
+        },
+    };
+}

package/dist/src/validate.d.ts

@@ -0,0 +1,13 @@
+/**
+ * One place where a wire payload becomes a typed value.
+ *
+ * Everything the IdP hands us — discovery, tokens, userinfo, management API
+ * responses — goes through here. A malformed payload raises an `IdpError` that
+ * names the offending field, rather than a `TypeError` three frames later on a
+ * property that was never there.
+ *
+ * `502` is the status: the failure is upstream, not in the caller's request.
+ */
+import type { z } from "zod";
+export declare function parseWire<T extends z.ZodType>(schema: T, value: unknown, what: string): z.output<T>;
+//# sourceMappingURL=validate.d.ts.map

package/dist/src/validate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate.d.ts","sourceRoot":"","sources":["../../src/validate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAS5B,wBAAgB,SAAS,CAAC,CAAC,SAAS,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,CAAC,EAAE,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAWnG"}

package/dist/src/validate.js

@@ -0,0 +1,28 @@
+/**
+ * One place where a wire payload becomes a typed value.
+ *
+ * Everything the IdP hands us — discovery, tokens, userinfo, management API
+ * responses — goes through here. A malformed payload raises an `IdpError` that
+ * names the offending field, rather than a `TypeError` three frames later on a
+ * property that was never there.
+ *
+ * `502` is the status: the failure is upstream, not in the caller's request.
+ */
+import { IdpError } from "./errors.js";
+/** `["workspaces", 0, "id"]` -> `"workspaces.0.id"`. */
+function issuePath(path) {
+    return path.length ? path.map(String).join(".") : "(root)";
+}
+export function parseWire(schema, value, what) {
+    const result = schema.safeParse(value);
+    if (result.success)
+        return result.data;
+    const detail = result.error.issues
+        .slice(0, 3)
+        .map((issue) => `${issuePath(issue.path)}: ${issue.message}`)
+        .join("; ");
+    throw new IdpError(`${what} returned a malformed payload (${detail})`, 502, {
+        issues: result.error.issues,
+        received: value,
+    });
+}