@willyim/idp 0.1.0 → 0.2.0

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":"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"}

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,
+    });
+}

package/dist/src/wire.d.ts

@@ -0,0 +1,164 @@
+/**
+ * The OIDC wire, as zod schemas: discovery, the token endpoint, and the claim
+ * set. These are not in `./schemas` with the management API because they are
+ * standards-defined — nothing generates them, and they never appear in our
+ * OpenAPI document.
+ *
+ * Two different postures live here on purpose:
+ *
+ *  - **Strict** on anything we act on. Without `token_endpoint` there is no
+ *    flow to run, and an `access_token` that is absent must not become `""`
+ *    and get written to a session row.
+ *  - **Tolerant** on claims. A user with no permissions, no workspaces, or no
+ *    display name is ordinary, not an error — those degrade to empty. Only
+ *    `sub` is genuinely required, since it is the identity.
+ *
+ * Unknown fields pass through everywhere: an IdP is allowed to grow.
+ */
+import { z } from "zod";
+export declare const PERMISSIONS_CLAIM = "https://willy.im/permissions";
+export declare const WORKSPACES_CLAIM = "https://willy.im/workspaces";
+/** The subset of the discovery document we use, plus the fields we may. */
+export declare const DiscoverySchema: z.ZodObject<{
+    issuer: z.ZodString;
+    authorization_endpoint: z.ZodString;
+    token_endpoint: z.ZodString;
+    userinfo_endpoint: z.ZodString;
+    end_session_endpoint: z.ZodOptional<z.ZodString>;
+    jwks_uri: z.ZodOptional<z.ZodString>;
+    /**
+     * Per-app session ceiling, in seconds. Not standard OIDC — an IdP extension
+     * the SDK clamps `session.expiresIn` against when present.
+     */
+    session_max_age: z.ZodOptional<z.ZodNumber>;
+}, z.core.$loose>;
+export type Discovery = z.output<typeof DiscoverySchema>;
+/** Token-endpoint output, camelCased so app code never sees the wire shape. */
+export declare const TokensSchema: z.ZodPipe<z.ZodObject<{
+    access_token: z.ZodString;
+    token_type: z.ZodDefault<z.ZodString>;
+    expires_in: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    refresh_token: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    id_token: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    scope: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+}, z.core.$loose>, z.ZodTransform<{
+    accessToken: string;
+    tokenType: string;
+    /** Seconds until the access token expires, when the IdP says. */
+    expiresIn: number | null;
+    refreshToken: string | null;
+    idToken: string | null;
+    scope: string | null;
+}, {
+    [x: string]: unknown;
+    access_token: string;
+    token_type: string;
+    expires_in?: number | null | undefined;
+    refresh_token?: string | null | undefined;
+    id_token?: string | null | undefined;
+    scope?: string | null | undefined;
+}>>;
+export type Tokens = z.output<typeof TokensSchema>;
+/** A tenant inside THIS app. `domain` is set for multi-domain apps, else null. */
+export declare const WorkspaceSchema: z.ZodObject<{
+    id: z.ZodString;
+    slug: z.ZodDefault<z.ZodString>;
+    name: z.ZodDefault<z.ZodString>;
+    domain: z.ZodPipe<z.ZodOptional<z.ZodNullable<z.ZodString>>, z.ZodTransform<string | null, string | null | undefined>>;
+    role: z.ZodDefault<z.ZodString>;
+}, z.core.$loose>;
+export type Workspace = z.output<typeof WorkspaceSchema>;
+/**
+ * The RFC 8693 `act` claim: present while an IdP admin is impersonating the
+ * user. Audit-only — tag your logs with it, never branch authorization on it.
+ */
+export declare const ActorSchema: z.ZodObject<{
+    sub: z.ZodString;
+    email: z.ZodOptional<z.ZodString>;
+}, z.core.$loose>;
+export type Actor = z.output<typeof ActorSchema>;
+/**
+ * Wire claims -> `Claims`. The `https://willy.im/*` namespace is unwrapped
+ * here: namespaced URI claims are an OIDC requirement, not something app code
+ * should ever have to type.
+ */
+export declare const ClaimsSchema: z.ZodPipe<z.ZodObject<{
+    sub: z.ZodString;
+    email: z.ZodCatch<z.ZodString>;
+    email_verified: z.ZodCatch<z.ZodBoolean>;
+    name: z.ZodCatch<z.ZodOptional<z.ZodNullable<z.ZodString>>>;
+    picture: z.ZodCatch<z.ZodOptional<z.ZodNullable<z.ZodString>>>;
+    image: z.ZodCatch<z.ZodOptional<z.ZodNullable<z.ZodString>>>;
+    "https://willy.im/permissions": z.ZodPipe<z.ZodCatch<z.ZodArray<z.ZodCatch<z.ZodNullable<z.ZodString>>>>, z.ZodTransform<string[], (string | null)[]>>;
+    "https://willy.im/workspaces": z.ZodPipe<z.ZodCatch<z.ZodArray<z.ZodCatch<z.ZodNullable<z.ZodObject<{
+        id: z.ZodString;
+        slug: z.ZodDefault<z.ZodString>;
+        name: z.ZodDefault<z.ZodString>;
+        domain: z.ZodPipe<z.ZodOptional<z.ZodNullable<z.ZodString>>, z.ZodTransform<string | null, string | null | undefined>>;
+        role: z.ZodDefault<z.ZodString>;
+    }, z.core.$loose>>>>>, z.ZodTransform<{
+        [x: string]: unknown;
+        id: string;
+        slug: string;
+        name: string;
+        domain: string | null;
+        role: string;
+    }[], ({
+        [x: string]: unknown;
+        id: string;
+        slug: string;
+        name: string;
+        domain: string | null;
+        role: string;
+    } | null)[]>>;
+    act: z.ZodCatch<z.ZodOptional<z.ZodNullable<z.ZodObject<{
+        sub: z.ZodString;
+        email: z.ZodOptional<z.ZodString>;
+    }, z.core.$loose>>>>;
+}, z.core.$loose>, z.ZodTransform<{
+    sub: string;
+    email: string;
+    emailVerified: boolean;
+    name: string | null;
+    image: string | null;
+    /** Product permissions granted in this app. Unwrapped from the namespace. */
+    permissions: string[];
+    /** Workspaces the user belongs to in this app. Unwrapped from the namespace. */
+    workspaces: {
+        [x: string]: unknown;
+        id: string;
+        slug: string;
+        name: string;
+        domain: string | null;
+        role: string;
+    }[];
+    actor: {
+        [x: string]: unknown;
+        sub: string;
+        email?: string | undefined;
+    } | null;
+}, {
+    [x: string]: unknown;
+    sub: string;
+    email: string;
+    email_verified: boolean;
+    "https://willy.im/permissions": string[];
+    "https://willy.im/workspaces": {
+        [x: string]: unknown;
+        id: string;
+        slug: string;
+        name: string;
+        domain: string | null;
+        role: string;
+    }[];
+    name?: string | null | undefined;
+    picture?: string | null | undefined;
+    image?: string | null | undefined;
+    act?: {
+        [x: string]: unknown;
+        sub: string;
+        email?: string | undefined;
+    } | null | undefined;
+}>>;
+export type Claims = z.output<typeof ClaimsSchema>;
+//# sourceMappingURL=wire.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"wire.d.ts","sourceRoot":"","sources":["../../src/wire.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAEvB,eAAO,MAAM,iBAAiB,iCAAiC,CAAA;AAC/D,eAAO,MAAM,gBAAgB,gCAAgC,CAAA;AAE7D,2EAA2E;AAC3E,eAAO,MAAM,eAAe;;;;;;;IAO1B;;;OAGG;;iBAEH,CAAA;AAEF,MAAM,MAAM,SAAS,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,eAAe,CAAC,CAAA;AAExD,+EAA+E;AAC/E,eAAO,MAAM,YAAY;;;;;;;;;;IAYrB,iEAAiE;;;;;;;;;;;;;GAKhE,CAAA;AAEL,MAAM,MAAM,MAAM,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,YAAY,CAAC,CAAA;AAElD,kFAAkF;AAClF,eAAO,MAAM,eAAe;;;;;;iBAM1B,CAAA;AAEF,MAAM,MAAM,SAAS,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,eAAe,CAAC,CAAA;AAExD;;;GAGG;AACH,eAAO,MAAM,WAAW;;;iBAGtB,CAAA;AAEF,MAAM,MAAM,KAAK,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,WAAW,CAAC,CAAA;AAMhD;;;;GAIG;AACH,eAAO,MAAM,YAAY;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;IAkBrB,6EAA6E;;IAE7E,gFAAgF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAG/E,CAAA;AAEL,MAAM,MAAM,MAAM,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,YAAY,CAAC,CAAA"}

package/dist/src/wire.js

@@ -0,0 +1,100 @@
+/**
+ * The OIDC wire, as zod schemas: discovery, the token endpoint, and the claim
+ * set. These are not in `./schemas` with the management API because they are
+ * standards-defined — nothing generates them, and they never appear in our
+ * OpenAPI document.
+ *
+ * Two different postures live here on purpose:
+ *
+ *  - **Strict** on anything we act on. Without `token_endpoint` there is no
+ *    flow to run, and an `access_token` that is absent must not become `""`
+ *    and get written to a session row.
+ *  - **Tolerant** on claims. A user with no permissions, no workspaces, or no
+ *    display name is ordinary, not an error — those degrade to empty. Only
+ *    `sub` is genuinely required, since it is the identity.
+ *
+ * Unknown fields pass through everywhere: an IdP is allowed to grow.
+ */
+import { z } from "zod";
+export const PERMISSIONS_CLAIM = "https://willy.im/permissions";
+export const WORKSPACES_CLAIM = "https://willy.im/workspaces";
+/** The subset of the discovery document we use, plus the fields we may. */
+export const DiscoverySchema = z.looseObject({
+    issuer: z.string(),
+    authorization_endpoint: z.string().url(),
+    token_endpoint: z.string().url(),
+    userinfo_endpoint: z.string().url(),
+    end_session_endpoint: z.string().url().optional(),
+    jwks_uri: z.string().url().optional(),
+    /**
+     * Per-app session ceiling, in seconds. Not standard OIDC — an IdP extension
+     * the SDK clamps `session.expiresIn` against when present.
+     */
+    session_max_age: z.number().optional(),
+});
+/** Token-endpoint output, camelCased so app code never sees the wire shape. */
+export const TokensSchema = z
+    .looseObject({
+    access_token: z.string().min(1),
+    token_type: z.string().default("Bearer"),
+    expires_in: z.number().nullish(),
+    refresh_token: z.string().nullish(),
+    id_token: z.string().nullish(),
+    scope: z.string().nullish(),
+})
+    .transform((raw) => ({
+    accessToken: raw.access_token,
+    tokenType: raw.token_type,
+    /** Seconds until the access token expires, when the IdP says. */
+    expiresIn: raw.expires_in ?? null,
+    refreshToken: raw.refresh_token ?? null,
+    idToken: raw.id_token ?? null,
+    scope: raw.scope ?? null,
+}));
+/** A tenant inside THIS app. `domain` is set for multi-domain apps, else null. */
+export const WorkspaceSchema = z.looseObject({
+    id: z.string(),
+    slug: z.string().default(""),
+    name: z.string().default(""),
+    domain: z.string().nullish().transform((value) => value || null),
+    role: z.string().default("member"),
+});
+/**
+ * The RFC 8693 `act` claim: present while an IdP admin is impersonating the
+ * user. Audit-only — tag your logs with it, never branch authorization on it.
+ */
+export const ActorSchema = z.looseObject({
+    sub: z.string().min(1),
+    email: z.string().optional(),
+});
+/** `.catch` per field, so one bad element degrades instead of failing a login. */
+const tolerantArray = (item) => z.array(item.nullable().catch(null)).catch([]).transform((values) => values.filter((v) => v !== null));
+/**
+ * Wire claims -> `Claims`. The `https://willy.im/*` namespace is unwrapped
+ * here: namespaced URI claims are an OIDC requirement, not something app code
+ * should ever have to type.
+ */
+export const ClaimsSchema = z
+    .looseObject({
+    sub: z.string().min(1),
+    email: z.string().catch(""),
+    email_verified: z.boolean().catch(false),
+    name: z.string().nullish().catch(null),
+    picture: z.string().nullish().catch(null),
+    image: z.string().nullish().catch(null),
+    [PERMISSIONS_CLAIM]: tolerantArray(z.string()),
+    [WORKSPACES_CLAIM]: tolerantArray(WorkspaceSchema),
+    act: ActorSchema.nullish().catch(null),
+})
+    .transform((raw) => ({
+    sub: raw.sub,
+    email: raw.email,
+    emailVerified: raw.email_verified,
+    name: raw.name || null,
+    image: raw.picture || raw.image || null,
+    /** Product permissions granted in this app. Unwrapped from the namespace. */
+    permissions: raw[PERMISSIONS_CLAIM],
+    /** Workspaces the user belongs to in this app. Unwrapped from the namespace. */
+    workspaces: raw[WORKSPACES_CLAIM],
+    actor: raw.act ?? null,
+}));

package/openapi/idp-api.json

@@ -23,6 +23,7 @@
     "/api/v1/applications": {
       "get": {
         "summary": "List registered applications",
+        "description": "Requires the superadmin token.",
         "security": [
           {
             "bearerAuth": []
@@ -109,6 +110,7 @@
     "/api/v1/users": {
       "get": {
         "summary": "List users",
+        "description": "Requires the superadmin token.",
         "security": [
           {
             "bearerAuth": []
@@ -179,6 +181,7 @@
     "/api/v1/workspaces": {
       "get": {
         "summary": "List workspaces",
+        "description": "Requires the superadmin token.",
         "security": [
           {
             "bearerAuth": []
@@ -592,9 +595,6 @@
           },
           "409": {
             "description": "Conflict (already a member, last admin, slug taken, …)"
-          },
-          "422": {
-            "description": "Body failed validation"
           }
         }
       }
@@ -1226,9 +1226,6 @@
           },
           "409": {
             "description": "Conflict (already a member, last admin, slug taken, …)"
-          },
-          "422": {
-            "description": "Body failed validation"
           }
         }
       }