@willyim/idp 0.1.1 → 0.2.0

package/README.md

@@ -7,13 +7,18 @@ someone is and what they may do. An app installing this package runs no auth
 framework: it owns one session table, which is a _handle_ to IdP truth rather
 than a record of it. No user table, no account table, no `ADMIN_EMAILS` list.
 
-Zero runtime dependencies — `fetch`, WebCrypto and `Request`/`Response` only, so
-the same build runs on Cloudflare Workers, Node 20+ and Bun.
+`zod` is the one runtime dependency: every payload the IdP sends — discovery,
+tokens, claims, management API responses — is parsed against a schema rather
+than cast, so a malformed response is an `IdpError` naming the field instead of
+a `TypeError` several frames later. Otherwise it is `fetch`, WebCrypto and
+`Request`/`Response` only, so the same build runs on Cloudflare Workers,
+Node 20+ and Bun.
 
 ```
-@willyim/idp               core: OIDC client + server sessions
-@willyim/idp/drizzle       the session store, and the `idp_session` table
-@willyim/idp/react-router  the auth route and the loader guards
+@willyim/idp                core: OIDC client + server sessions
+@willyim/idp/drizzle        the session store, and the `idp_session` table
+@willyim/idp/react-router   the auth route and the loader guards
+@willyim/idp/schemas        the management API wire shapes, as zod schemas
 ```
 
 ## Install
@@ -272,15 +277,71 @@ const idp = createIdp({
 })
 ```
 
+## End-user API keys
+
+Keys an app's own users create to call *that app's* API. The IdP is the key
+store: the app mints, lists, revokes and validates `wak_…` tokens over the
+management API and never persists a plaintext or a hash.
+
+```ts
+import { createUserKeys } from "@willyim/idp"
+
+const keys = createUserKeys({
+  baseUrl: "https://idp.willy.im", // the API is at the root, not under /auth
+  token: env.IDP_MANAGEMENT_KEY, //  the app's own wim_… key
+  app: "luchy",
+  cache: { ttlMs: 60_000 }, // validation cache; revocation lag is bounded by it
+})
+
+// Mint — the plaintext exists exactly once, in this response.
+const minted = await keys.create({
+  userId: session.userId,
+  name: "cli",
+  scopes: ["analytics:read"], // must be in the app's product permission catalog
+  workspaceId: session.workspaceId,
+})
+
+// Check, on the request path.
+const auth = await keys.authenticate(request, { scopes: ["analytics:read"] })
+if (!auth.ok) return new Response(auth.reason, { status: auth.status })
+auth.key // { keyId, userId, workspaceId, scopes, name }
+```
+
+`authenticate` reads `Authorization: Bearer …`, then `X-API-Key`, and returns a
+result rather than throwing so the caller owns the response shape. Underneath,
+`validate` caches verdicts by digest of the token (60s for a hit, 10s for a
+miss, never for a failed round trip) and collapses concurrent checks of the same
+token into one request. Revoking through some other channel is visible only once
+the entry expires; `forget(token)` drops it immediately when you hold the
+plaintext.
+
+Filter with `list({ userId, workspaceId })`, revoke with `revoke(id)`. Scope
+enforcement is the app's job — the IdP stores the scopes and reports them.
+
+Only for **secret** credentials. A key embedded in a web 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 and
+gate them on `Origin` plus rate limiting.
+
 ## Management API types
 
-The IdP's `/api/v1/*` management surface is not part of this package's public
-API in v1. The types for it are generated from the IdP's OpenAPI document —
-`npm run openapi` refreshes both `openapi/idp-api.json` and
-`src/generated/idp-api.d.ts` — so that when management calls are added they
-cannot be hand-written. The OIDC endpoints are not in that document and never
-will be: they are standards-defined and discovered at runtime from
-`.well-known`.
+Endpoints without sugar of their own go through `createManagementApi`, whose
+paths, methods, path parameters, bodies and response shapes all come from the
+operations table in `@willyim/idp/schemas` — one zod definition per shape,
+which also builds `openapi/idp-api.json` (`npm run openapi`) and which the IdP
+itself validates incoming requests with. A typo in a path is a compile error,
+not a 404 in production, and a response that doesn't match its schema throws
+instead of reaching your code as `undefined`.
+
+```ts
+const api = createManagementApi({ baseUrl, token })
+const { members } = await api.request("get", "/api/v1/apps/{app}/members", {
+  params: { app: "luchy" },
+})
+```
+
+The OIDC endpoints are not in that document and never will be: they are
+standards-defined and discovered at runtime from `.well-known`.
 
 ## Licence
 

package/dist/src/api.d.ts

@@ -1,64 +1,41 @@
 /**
  * The typed door to the IdP's `/api/v1/*` management surface.
  *
- * Nothing in v1 goes through it — the management key, the directory API and
- * end-user API keys were all cut — but it exists now so that the *first*
- * management call can't be hand-written. Paths, methods, path parameters,
- * request bodies and success shapes all come from `src/generated/idp-api.d.ts`,
- * which `npm run openapi` regenerates from apps/idp's OpenAPI document. A typo
- * in a path is a compile error, not a 404 in production.
+ * Paths, methods, request bodies and success shapes all come from the
+ * operations table in `./schemas/operations.ts` — the same table that builds
+ * the OpenAPI document and that `apps/idp` validates requests with. A typo in
+ * a path is a compile error, not a 404 in production, and a response that
+ * doesn't match its schema raises an `IdpError` naming the field rather than
+ * surfacing as `undefined` somewhere downstream.
  *
- * Deliberately not exported from any entrypoint: it is internal until the
- * management surface is back in scope. Types only at runtime, so core stays
- * dependency-free.
+ * Path parameters are read off the path template itself, so `{app}` in the
+ * string is what makes `params.app` required.
+ *
+ * This is the escape hatch for any endpoint without sugar of its own; see
+ * `user-keys.ts` for the shaped client over the end-user key endpoints.
  */
-import type { paths } from "./generated/idp-api.js";
-export type ApiPaths = paths;
-export type Method = "get" | "put" | "post" | "delete" | "patch";
-/** The paths that actually declare `M` — `paths` types the rest as `never`. */
-export type PathsFor<M extends Method> = {
-    [P in keyof paths]: paths[P] extends {
-        [K in M]: object;
-    } ? P : never;
-}[keyof paths];
-export type Operation<P extends keyof paths, M extends Method> = M extends keyof paths[P] ? paths[P][M] : never;
-type PathParams<O> = O extends {
-    parameters: {
-        path: infer T;
-    };
-} ? T extends object ? T : never : never;
-type RequestBody<O> = O extends {
-    requestBody: {
-        content: {
-            "application/json": infer B;
-        };
-    };
-} ? B : never;
-/** The 200 or 201 JSON body, whichever this operation declares. */
-type SuccessBody<O> = O extends {
-    responses: infer R;
-} ? R extends {
-    200: {
-        content: {
-            "application/json": infer T;
-        };
-    };
-} ? T : R extends {
-    201: {
-        content: {
-            "application/json": infer T;
-        };
-    };
-} ? T : never : never;
-export type RequestOptions<O> = ([PathParams<O>] extends [never] ? {
+import type { z } from "zod";
+import { type HttpMethod, type OperationFor, type PathParamNames, type PathsFor } from "./schemas/operations.js";
+export type Method = HttpMethod;
+export type { PathsFor };
+/** What the caller must supply: `{app}` in the path becomes `params.app`. */
+type PathParams<P extends string> = [PathParamNames<P>] extends [never] ? {
     params?: undefined;
 } : {
-    params: PathParams<O>;
-}) & ([RequestBody<O>] extends [never] ? {
-    body?: undefined;
+    params: Record<PathParamNames<P>, string>;
+};
+type RequestBody<O> = O extends {
+    input: infer S extends z.ZodType;
+} ? {
+    body: z.input<S>;
 } : {
-    body: RequestBody<O>;
-}) & {
+    body?: undefined;
+};
+/** The 200 or 201 JSON body, whichever this operation declares. */
+export type SuccessBody<O> = O extends {
+    success: infer S extends z.ZodType;
+} ? z.output<S> : never;
+export type RequestOptions<P extends string, O> = PathParams<P> & RequestBody<O> & {
     query?: Record<string, string | number | boolean | undefined>;
     signal?: AbortSignal;
 };
@@ -70,8 +47,7 @@ export type ManagementApiOptions = {
     fetch?: typeof fetch;
 };
 export declare function createManagementApi(options: ManagementApiOptions): {
-    request<M extends Method, P extends PathsFor<M>>(method: M, path: P, init?: RequestOptions<Operation<P, M>>): Promise<SuccessBody<Operation<P, M>>>;
+    request<M extends Method, P extends PathsFor<M>>(method: M, path: P, init?: RequestOptions<P, OperationFor<M, P>>): Promise<SuccessBody<OperationFor<M, P>>>;
 };
 export type ManagementApi = ReturnType<typeof createManagementApi>;
-export {};
 //# sourceMappingURL=api.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"api.d.ts","sourceRoot":"","sources":["../../src/api.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"api.d.ts","sourceRoot":"","sources":["../../src/api.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAG5B,OAAO,EAEL,KAAK,UAAU,EAEf,KAAK,YAAY,EACjB,KAAK,cAAc,EACnB,KAAK,QAAQ,EACd,MAAM,yBAAyB,CAAA;AAGhC,MAAM,MAAM,MAAM,GAAG,UAAU,CAAA;AAC/B,YAAY,EAAE,QAAQ,EAAE,CAAA;AAExB,6EAA6E;AAC7E,KAAK,UAAU,CAAC,CAAC,SAAS,MAAM,IAAI,CAAC,cAAc,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,KAAK,CAAC,GACnE;IAAE,MAAM,CAAC,EAAE,SAAS,CAAA;CAAE,GACtB;IAAE,MAAM,EAAE,MAAM,CAAC,cAAc,CAAC,CAAC,CAAC,EAAE,MAAM,CAAC,CAAA;CAAE,CAAA;AAEjD,KAAK,WAAW,CAAC,CAAC,IAAI,CAAC,SAAS;IAAE,KAAK,EAAE,MAAM,CAAC,SAAS,CAAC,CAAC,OAAO,CAAA;CAAE,GAChE;IAAE,IAAI,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAA;CAAE,GACpB;IAAE,IAAI,CAAC,EAAE,SAAS,CAAA;CAAE,CAAA;AAExB,mEAAmE;AACnE,MAAM,MAAM,WAAW,CAAC,CAAC,IAAI,CAAC,SAAS;IAAE,OAAO,EAAE,MAAM,CAAC,SAAS,CAAC,CAAC,OAAO,CAAA;CAAE,GACzE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,GACX,KAAK,CAAA;AAET,MAAM,MAAM,cAAc,CAAC,CAAC,SAAS,MAAM,EAAE,CAAC,IAAI,UAAU,CAAC,CAAC,CAAC,GAC7D,WAAW,CAAC,CAAC,CAAC,GAAG;IACf,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,SAAS,CAAC,CAAA;IAC7D,MAAM,CAAC,EAAE,WAAW,CAAA;CACrB,CAAA;AAEH,MAAM,MAAM,oBAAoB,GAAG;IACjC,8EAA8E;IAC9E,OAAO,EAAE,MAAM,CAAA;IACf,4DAA4D;IAC5D,KAAK,EAAE,MAAM,CAAA;IACb,KAAK,CAAC,EAAE,OAAO,KAAK,CAAA;CACrB,CAAA;AAED,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,oBAAoB;YAK/C,CAAC,SAAS,MAAM,EAAE,CAAC,SAAS,QAAQ,CAAC,CAAC,CAAC,UAC3C,CAAC,QACH,CAAC,SACD,cAAc,CAAC,CAAC,EAAE,YAAY,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GAC1C,OAAO,CAAC,WAAW,CAAC,YAAY,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;EAuC9C;AAED,MAAM,MAAM,aAAa,GAAG,UAAU,CAAC,OAAO,mBAAmB,CAAC,CAAA"}

package/dist/src/api.js

@@ -1,23 +1,28 @@
 /**
  * The typed door to the IdP's `/api/v1/*` management surface.
  *
- * Nothing in v1 goes through it — the management key, the directory API and
- * end-user API keys were all cut — but it exists now so that the *first*
- * management call can't be hand-written. Paths, methods, path parameters,
- * request bodies and success shapes all come from `src/generated/idp-api.d.ts`,
- * which `npm run openapi` regenerates from apps/idp's OpenAPI document. A typo
- * in a path is a compile error, not a 404 in production.
+ * Paths, methods, request bodies and success shapes all come from the
+ * operations table in `./schemas/operations.ts` — the same table that builds
+ * the OpenAPI document and that `apps/idp` validates requests with. A typo in
+ * a path is a compile error, not a 404 in production, and a response that
+ * doesn't match its schema raises an `IdpError` naming the field rather than
+ * surfacing as `undefined` somewhere downstream.
  *
- * Deliberately not exported from any entrypoint: it is internal until the
- * management surface is back in scope. Types only at runtime, so core stays
- * dependency-free.
+ * Path parameters are read off the path template itself, so `{app}` in the
+ * string is what makes `params.app` required.
+ *
+ * This is the escape hatch for any endpoint without sugar of its own; see
+ * `user-keys.ts` for the shaped client over the end-user key endpoints.
  */
-import { IdpError } from "./client.js";
+import { IdpError } from "./errors.js";
+import { lookup, } from "./schemas/operations.js";
+import { parseWire } from "./validate.js";
 export function createManagementApi(options) {
     const baseUrl = options.baseUrl.replace(/\/+$/, "");
     const doFetch = options.fetch ?? globalThis.fetch;
     return {
         async request(method, path, init = {}) {
+            const operation = lookup(method, path);
             const params = (init.params ?? {});
             const rendered = String(path).replace(/\{([^}]+)\}/g, (_, name) => {
                 const value = params[name];
@@ -44,7 +49,7 @@ export function createManagementApi(options) {
             if (!response.ok) {
                 throw new IdpError(`${method.toUpperCase()} ${rendered} failed (${response.status})`, response.status, json);
             }
-            return json;
+            return parseWire(operation.success, json, `${method.toUpperCase()} ${rendered}`);
         },
     };
 }

package/dist/src/claims.d.ts

@@ -1,41 +1,16 @@
 /**
- * The claim set the IdP hands back, with the `https://willy.im/*` namespace
- * unwrapped. Namespaced URI claims are an OIDC requirement, not something app
- * code should ever have to type — `claims.permissions`, not
- * `claims["https://willy.im/permissions"]`.
+ * Claim types and the permission check over them. The shapes themselves live
+ * in `./wire.ts` as zod schemas — this module re-exports them so app code has
+ * one obvious import, and owns `grants`, which is logic rather than parsing.
  */
-export declare const PERMISSIONS_CLAIM = "https://willy.im/permissions";
-export declare const WORKSPACES_CLAIM = "https://willy.im/workspaces";
-/** A tenant inside THIS app. `domain` is set for multi-domain apps, else null. */
-export type Workspace = {
-    id: string;
-    slug: string;
-    name: string;
-    domain: string | null;
-    role: string;
-};
+import { type Claims } from "./wire.js";
+export { ActorSchema, ClaimsSchema, PERMISSIONS_CLAIM, WORKSPACES_CLAIM, WorkspaceSchema, type Actor, type Claims, type Workspace, } from "./wire.js";
 /**
- * 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.
+ * Wire claims -> `Claims`. Tolerant by design: a missing or malformed optional
+ * claim degrades to an empty value. Only `sub` is required — without it there
+ * is no identity to seat a session on.
  */
-export type Actor = {
-    sub: string;
-    email?: string;
-};
-export type Claims = {
-    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: Workspace[];
-    actor: Actor | null;
-};
-/** Wire claims -> `Claims`. Tolerant: a missing claim is an empty value, not a throw. */
-export declare function normalizeClaims(payload: Record<string, unknown>): Claims;
+export declare function normalizeClaims(payload: unknown): Claims;
 /**
  * Does this permission set grant `permission`? Exact match, plus prefix
  * wildcards — a grant of `invoices:*` covers `invoices:read`, and `*` covers

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

@@ -1 +1 @@
-{"version":3,"file":"claims.d.ts","sourceRoot":"","sources":["../../src/claims.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,eAAO,MAAM,iBAAiB,iCAAiC,CAAA;AAC/D,eAAO,MAAM,gBAAgB,gCAAgC,CAAA;AAE7D,kFAAkF;AAClF,MAAM,MAAM,SAAS,GAAG;IACtB,EAAE,EAAE,MAAM,CAAA;IACV,IAAI,EAAE,MAAM,CAAA;IACZ,IAAI,EAAE,MAAM,CAAA;IACZ,MAAM,EAAE,MAAM,GAAG,IAAI,CAAA;IACrB,IAAI,EAAE,MAAM,CAAA;CACb,CAAA;AAED;;;GAGG;AACH,MAAM,MAAM,KAAK,GAAG;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,CAAA;AAEnD,MAAM,MAAM,MAAM,GAAG;IACnB,GAAG,EAAE,MAAM,CAAA;IACX,KAAK,EAAE,MAAM,CAAA;IACb,aAAa,EAAE,OAAO,CAAA;IACtB,IAAI,EAAE,MAAM,GAAG,IAAI,CAAA;IACnB,KAAK,EAAE,MAAM,GAAG,IAAI,CAAA;IACpB,6EAA6E;IAC7E,WAAW,EAAE,MAAM,EAAE,CAAA;IACrB,gFAAgF;IAChF,UAAU,EAAE,SAAS,EAAE,CAAA;IACvB,KAAK,EAAE,KAAK,GAAG,IAAI,CAAA;CACpB,CAAA;AAED,yFAAyF;AACzF,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAqBxE;AAED;;;;;GAKG;AACH,wBAAgB,MAAM,CAAC,WAAW,EAAE,SAAS,MAAM,EAAE,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAOlF"}
+{"version":3,"file":"claims.d.ts","sourceRoot":"","sources":["../../src/claims.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAgB,KAAK,MAAM,EAAE,MAAM,WAAW,CAAA;AAGrD,OAAO,EACL,WAAW,EACX,YAAY,EACZ,iBAAiB,EACjB,gBAAgB,EAChB,eAAe,EACf,KAAK,KAAK,EACV,KAAK,MAAM,EACX,KAAK,SAAS,GACf,MAAM,WAAW,CAAA;AAElB;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,OAAO,GAAG,MAAM,CAExD;AAED;;;;;GAKG;AACH,wBAAgB,MAAM,CAAC,WAAW,EAAE,SAAS,MAAM,EAAE,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAOlF"}

package/dist/src/claims.js

@@ -1,33 +1,18 @@
 /**
- * The claim set the IdP hands back, with the `https://willy.im/*` namespace
- * unwrapped. Namespaced URI claims are an OIDC requirement, not something app
- * code should ever have to type — `claims.permissions`, not
- * `claims["https://willy.im/permissions"]`.
+ * Claim types and the permission check over them. The shapes themselves live
+ * in `./wire.ts` as zod schemas — this module re-exports them so app code has
+ * one obvious import, and owns `grants`, which is logic rather than parsing.
+ */
+import { ClaimsSchema } from "./wire.js";
+import { parseWire } from "./validate.js";
+export { ActorSchema, ClaimsSchema, PERMISSIONS_CLAIM, WORKSPACES_CLAIM, WorkspaceSchema, } from "./wire.js";
+/**
+ * Wire claims -> `Claims`. Tolerant by design: a missing or malformed optional
+ * claim degrades to an empty value. Only `sub` is required — without it there
+ * is no identity to seat a session on.
  */
-export const PERMISSIONS_CLAIM = "https://willy.im/permissions";
-export const WORKSPACES_CLAIM = "https://willy.im/workspaces";
-/** Wire claims -> `Claims`. Tolerant: a missing claim is an empty value, not a throw. */
 export function normalizeClaims(payload) {
-    return {
-        sub: str(payload.sub) ?? "",
-        email: str(payload.email) ?? "",
-        emailVerified: payload.email_verified === true,
-        name: str(payload.name),
-        image: str(payload.picture) ?? str(payload.image),
-        permissions: Array.isArray(payload[PERMISSIONS_CLAIM])
-            ? payload[PERMISSIONS_CLAIM].map(String)
-            : [],
-        workspaces: Array.isArray(payload[WORKSPACES_CLAIM])
-            ? payload[WORKSPACES_CLAIM].map((w) => ({
-                id: String(w.id ?? ""),
-                slug: String(w.slug ?? ""),
-                name: String(w.name ?? ""),
-                domain: str(w.domain),
-                role: String(w.role ?? "member"),
-            }))
-            : [],
-        actor: actorOf(payload.act),
-    };
+    return parseWire(ClaimsSchema, payload, "userinfo");
 }
 /**
  * Does this permission set grant `permission`? Exact match, plus prefix
@@ -46,16 +31,3 @@ export function grants(permissions, permission) {
     }
     return false;
 }
-function str(value) {
-    return typeof value === "string" && value ? value : null;
-}
-function actorOf(value) {
-    if (!value || typeof value !== "object")
-        return null;
-    const act = value;
-    const sub = str(act.sub);
-    if (!sub)
-        return null;
-    const email = str(act.email);
-    return email ? { sub, email } : { sub };
-}

package/dist/src/client.d.ts

@@ -6,7 +6,18 @@
  * `fetch` + WebCrypto only, so it runs anywhere the platform is web-standard.
  */
 import { type Claims } from "./claims.js";
-export declare const DEFAULT_SCOPES: string[];
+import { type Discovery } from "./wire.js";
+export { IdpError } from "./errors.js";
+export type { Discovery, Tokens } from "./wire.js";
+/**
+ * Every scope the IdP advertises in `scopes_supported`. Typed rather than
+ * `string[]` so a typo (`"offline-access"`) is a compile error instead of a
+ * redirect the IdP rejects at runtime. Widen this when the IdP grows a scope.
+ */
+export declare const SUPPORTED_SCOPES: readonly ["openid", "profile", "email", "offline_access"];
+export type IdpScope = (typeof SUPPORTED_SCOPES)[number];
+/** What `authorizationUrl` asks for when a caller says nothing. */
+export declare const DEFAULT_SCOPES: readonly IdpScope[];
 export type IdpClientOptions = {
     /**
      * The OIDC issuer, including the basepath the IdP is mounted on:
@@ -17,45 +28,16 @@ export type IdpClientOptions = {
     clientId: string;
     clientSecret: string;
     /** Default scopes for `authorizationUrl`. `offline_access` buys refresh tokens. */
-    scopes?: string[];
+    scopes?: readonly IdpScope[];
     /** Override `fetch` — tests, instrumentation, a Worker's bound fetcher. */
     fetch?: typeof fetch;
 };
-/** The subset of the discovery document we use, plus the fields we may. */
-export type Discovery = {
-    issuer: string;
-    authorization_endpoint: string;
-    token_endpoint: string;
-    userinfo_endpoint: string;
-    end_session_endpoint?: string;
-    jwks_uri?: string;
-    /**
-     * Per-app session ceiling, in seconds. Not standard OIDC — an IdP extension
-     * the SDK clamps `session.expiresIn` against when present.
-     */
-    session_max_age?: number;
-};
-/** Token-endpoint output, camelCased so app code never sees the wire shape. */
-export type Tokens = {
-    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;
-};
-export declare class IdpError extends Error {
-    readonly status: number;
-    readonly body: unknown;
-    constructor(message: string, status: number, body?: unknown);
-}
 export type AuthorizationUrlInput = {
     redirectUri: string;
     state: string;
     /** The S256 challenge. PKCE is not optional — see `createPkce`. */
     codeChallenge: string;
-    scopes?: string[];
+    scopes?: readonly IdpScope[];
     /** `login` to force re-authentication, `none` for a silent check. */
     prompt?: string;
     loginHint?: string;
@@ -75,9 +57,23 @@ export declare function createIdpClient(options: IdpClientOptions): {
         code: string;
         redirectUri: string;
         codeVerifier: string;
-    }): Promise<Tokens>;
+    }): Promise<{
+        accessToken: string;
+        tokenType: string;
+        expiresIn: number | null;
+        refreshToken: string | null;
+        idToken: string | null;
+        scope: string | null;
+    }>;
     /** Requires `offline_access` at login. Throws `IdpError` once the grant is gone. */
-    refresh(refreshToken: string): Promise<Tokens>;
+    refresh(refreshToken: string): Promise<{
+        accessToken: string;
+        tokenType: string;
+        expiresIn: number | null;
+        refreshToken: string | null;
+        idToken: string | null;
+        scope: string | null;
+    }>;
     /**
      * Live claims for an access token. Unlike the id_token — a login-time
      * snapshot — this reflects permissions and workspaces as they are *now*,

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

@@ -1 +1 @@
-{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/client.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAmB,KAAK,MAAM,EAAE,MAAM,aAAa,CAAA;AAG1D,eAAO,MAAM,cAAc,UAAmD,CAAA;AAE9E,MAAM,MAAM,gBAAgB,GAAG;IAC7B;;;;OAIG;IACH,MAAM,EAAE,MAAM,CAAA;IACd,QAAQ,EAAE,MAAM,CAAA;IAChB,YAAY,EAAE,MAAM,CAAA;IACpB,mFAAmF;IACnF,MAAM,CAAC,EAAE,MAAM,EAAE,CAAA;IACjB,2EAA2E;IAC3E,KAAK,CAAC,EAAE,OAAO,KAAK,CAAA;CACrB,CAAA;AAED,2EAA2E;AAC3E,MAAM,MAAM,SAAS,GAAG;IACtB,MAAM,EAAE,MAAM,CAAA;IACd,sBAAsB,EAAE,MAAM,CAAA;IAC9B,cAAc,EAAE,MAAM,CAAA;IACtB,iBAAiB,EAAE,MAAM,CAAA;IACzB,oBAAoB,CAAC,EAAE,MAAM,CAAA;IAC7B,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB;;;OAGG;IACH,eAAe,CAAC,EAAE,MAAM,CAAA;CACzB,CAAA;AAED,+EAA+E;AAC/E,MAAM,MAAM,MAAM,GAAG;IACnB,WAAW,EAAE,MAAM,CAAA;IACnB,SAAS,EAAE,MAAM,CAAA;IACjB,iEAAiE;IACjE,SAAS,EAAE,MAAM,GAAG,IAAI,CAAA;IACxB,YAAY,EAAE,MAAM,GAAG,IAAI,CAAA;IAC3B,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;IACtB,KAAK,EAAE,MAAM,GAAG,IAAI,CAAA;CACrB,CAAA;AAED,qBAAa,QAAS,SAAQ,KAAK;IACjC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAA;gBACV,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO;CAM5D;AAED,MAAM,MAAM,qBAAqB,GAAG;IAClC,WAAW,EAAE,MAAM,CAAA;IACnB,KAAK,EAAE,MAAM,CAAA;IACb,mEAAmE;IACnE,aAAa,EAAE,MAAM,CAAA;IACrB,MAAM,CAAC,EAAE,MAAM,EAAE,CAAA;IACjB,qEAAqE;IACrE,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB,CAAA;AAED,MAAM,MAAM,SAAS,GAAG,UAAU,CAAC,OAAO,eAAe,CAAC,CAAA;AAE1D,oDAAoD;AACpD,wBAAsB,UAAU,IAAI,OAAO,CAAC;IAAE,YAAY,EAAE,MAAM,CAAC;IAAC,aAAa,EAAE,MAAM,CAAA;CAAE,CAAC,CAG3F;AAED,wBAAgB,eAAe,CAAC,OAAO,EAAE,gBAAgB;oBAOlC,OAAO,CAAC,SAAS,CAAC;IAiDrC,2CAA2C;4BACb,qBAAqB,GAAG,OAAO,CAAC,MAAM,CAAC;IAerE,oFAAoF;wBAChE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,CAAC;QAAC,YAAY,EAAE,MAAM,CAAA;KAAE;IAY/E,oFAAoF;0BAC9D,MAAM;IAO5B;;;;OAIG;0BACyB,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAepD;;;;;;;;;;;;;;;;;;;OAmBG;qBACoB;QACrB,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;QACvB,UAAU,CAAC,EAAE,MAAM,CAAA;KACpB,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;EAU7B"}
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/client.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAmB,KAAK,MAAM,EAAE,MAAM,aAAa,CAAA;AAI1D,OAAO,EAAiC,KAAK,SAAS,EAAe,MAAM,WAAW,CAAA;AAEtF,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAA;AACtC,YAAY,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,WAAW,CAAA;AAElD;;;;GAIG;AACH,eAAO,MAAM,gBAAgB,2DAA4D,CAAA;AAEzF,MAAM,MAAM,QAAQ,GAAG,CAAC,OAAO,gBAAgB,CAAC,CAAC,MAAM,CAAC,CAAA;AAExD,mEAAmE;AACnE,eAAO,MAAM,cAAc,EAAE,SAAS,QAAQ,EAAqB,CAAA;AAEnE,MAAM,MAAM,gBAAgB,GAAG;IAC7B;;;;OAIG;IACH,MAAM,EAAE,MAAM,CAAA;IACd,QAAQ,EAAE,MAAM,CAAA;IAChB,YAAY,EAAE,MAAM,CAAA;IACpB,mFAAmF;IACnF,MAAM,CAAC,EAAE,SAAS,QAAQ,EAAE,CAAA;IAC5B,2EAA2E;IAC3E,KAAK,CAAC,EAAE,OAAO,KAAK,CAAA;CACrB,CAAA;AAED,MAAM,MAAM,qBAAqB,GAAG;IAClC,WAAW,EAAE,MAAM,CAAA;IACnB,KAAK,EAAE,MAAM,CAAA;IACb,mEAAmE;IACnE,aAAa,EAAE,MAAM,CAAA;IACrB,MAAM,CAAC,EAAE,SAAS,QAAQ,EAAE,CAAA;IAC5B,qEAAqE;IACrE,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB,CAAA;AAED,MAAM,MAAM,SAAS,GAAG,UAAU,CAAC,OAAO,eAAe,CAAC,CAAA;AAE1D,oDAAoD;AACpD,wBAAsB,UAAU,IAAI,OAAO,CAAC;IAAE,YAAY,EAAE,MAAM,CAAC;IAAC,aAAa,EAAE,MAAM,CAAA;CAAE,CAAC,CAG3F;AAED,wBAAgB,eAAe,CAAC,OAAO,EAAE,gBAAgB;oBAOlC,OAAO,CAAC,SAAS,CAAC;IA0CrC,2CAA2C;4BACb,qBAAqB,GAAG,OAAO,CAAC,MAAM,CAAC;IAerE,oFAAoF;wBAChE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,CAAC;QAAC,YAAY,EAAE,MAAM,CAAA;KAAE;;;;;;;;IAY/E,oFAAoF;0BAC9D,MAAM;;;;;;;;IAO5B;;;;OAIG;0BACyB,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAepD;;;;;;;;;;;;;;;;;;;OAmBG;qBACoB;QACrB,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;QACvB,UAAU,CAAC,EAAE,MAAM,CAAA;KACpB,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;EAU7B"}

package/dist/src/client.js

@@ -7,17 +7,18 @@
  */
 import { normalizeClaims } from "./claims.js";
 import { randomToken, sha256Base64url } from "./crypto.js";
-export const DEFAULT_SCOPES = ["openid", "profile", "email", "offline_access"];
-export class IdpError extends Error {
-    status;
-    body;
-    constructor(message, status, body) {
-        super(message);
-        this.name = "IdpError";
-        this.status = status;
-        this.body = body;
-    }
-}
+import { IdpError } from "./errors.js";
+import { parseWire } from "./validate.js";
+import { DiscoverySchema, TokensSchema } from "./wire.js";
+export { IdpError } from "./errors.js";
+/**
+ * Every scope the IdP advertises in `scopes_supported`. Typed rather than
+ * `string[]` so a typo (`"offline-access"`) is a compile error instead of a
+ * redirect the IdP rejects at runtime. Widen this when the IdP grows a scope.
+ */
+export const SUPPORTED_SCOPES = ["openid", "profile", "email", "offline_access"];
+/** What `authorizationUrl` asks for when a caller says nothing. */
+export const DEFAULT_SCOPES = SUPPORTED_SCOPES;
 /** A fresh PKCE verifier and its S256 challenge. */
 export async function createPkce() {
     const codeVerifier = randomToken(32);
@@ -44,7 +45,7 @@ export function createIdpClient(options) {
                 cached = null;
                 throw new IdpError(`discovery failed (${response.status})`, response.status, await text(response));
             }
-            return (await response.json());
+            return parseWire(DiscoverySchema, await response.json().catch(() => null), "discovery");
         })();
         return cached;
     }
@@ -57,18 +58,11 @@ export function createIdpClient(options) {
             headers: { "content-type": "application/x-www-form-urlencoded", accept: "application/json" },
             body,
         });
-        const json = (await response.json().catch(() => null));
+        const json = await response.json().catch(() => null);
         if (!response.ok || !json) {
             throw new IdpError(`${what} failed (${response.status})`, response.status, json);
         }
-        return {
-            accessToken: String(json.access_token ?? ""),
-            tokenType: String(json.token_type ?? "Bearer"),
-            expiresIn: typeof json.expires_in === "number" ? json.expires_in : null,
-            refreshToken: typeof json.refresh_token === "string" ? json.refresh_token : null,
-            idToken: typeof json.id_token === "string" ? json.id_token : null,
-            scope: typeof json.scope === "string" ? json.scope : null,
-        };
+        return parseWire(TokensSchema, json, what);
     }
     return {
         discover,
@@ -115,7 +109,7 @@ export function createIdpClient(options) {
             if (!response.ok) {
                 throw new IdpError(`userinfo failed (${response.status})`, response.status, await text(response));
             }
-            return normalizeClaims((await response.json()));
+            return normalizeClaims(await response.json().catch(() => null));
         },
         /**
          * RP-initiated logout, built from the `end_session_endpoint` in discovery —