@willyim/idp 0.1.0 → 0.2.0

package/dist/src/schemas/openapi.js

@@ -0,0 +1,110 @@
+/**
+ * The published OpenAPI document, built from `./operations.ts`.
+ *
+ * `apps/idp` serves this at `/api/v1/openapi.json`; `npm run openapi` writes
+ * the same object to `openapi/idp-api.json` so the snapshot in the repo is
+ * always what the server would answer.
+ */
+import { z } from "zod";
+import { lookup, operations } from "./operations.js";
+/**
+ * Responses describe what the API *returns*, so they use zod's output types.
+ * Request bodies describe what a caller may *send*, which is a different shape:
+ * a field with a `.default()` is optional on the way in and guaranteed on the
+ * way out. Emitting output types for both would mark every defaulted field
+ * `required` and force callers to supply values the API would have defaulted.
+ */
+const json = (schema) => z.toJSONSchema(schema);
+const jsonInput = (schema) => z.toJSONSchema(schema, { io: "input" });
+const DESCRIPTION = "Management API for the willy.im identity provider. Authenticate with `Authorization: Bearer <token>`. Two kinds of token: the superadmin `ADMIN_API_TOKEN` (every app) and per-app **scoped API keys** minted in the admin console (one app, a fixed permission set). The cross-app list endpoints below require the superadmin token. Application registration is done in the admin console (better-auth ties client creation to an admin session).";
+function pathParamNames(path) {
+    return [...path.matchAll(/\{([^}]+)\}/g)].map((match) => match[1]);
+}
+function parametersFor(path, def) {
+    const pathParams = pathParamNames(path).map((name) => ({
+        name,
+        in: "path",
+        required: true,
+        ...(def.params?.[name] ? { description: def.params[name] } : {}),
+        schema: { type: "string" },
+    }));
+    const queryParams = (def.query ?? []).map((param) => ({
+        name: param.name,
+        in: "query",
+        required: param.required ?? false,
+        ...(param.description ? { description: param.description } : {}),
+        schema: { type: "string" },
+    }));
+    return [...pathParams, ...queryParams];
+}
+function operationObject(method, path, def) {
+    const scoped = def.permission !== undefined;
+    const write = method !== "get";
+    const parameters = parametersFor(path, def);
+    return {
+        summary: def.summary,
+        description: def.description ??
+            (scoped
+                ? `Requires \`${def.permission}\` on the path app (or the superadmin token).`
+                : "Requires the superadmin token."),
+        security: [{ bearerAuth: [] }],
+        ...(parameters.length ? { parameters } : {}),
+        ...(def.input
+            ? {
+                requestBody: {
+                    required: true,
+                    content: { "application/json": { schema: jsonInput(def.input) } },
+                },
+            }
+            : {}),
+        responses: {
+            [def.successCode]: {
+                description: "OK",
+                content: { "application/json": { schema: json(def.success) } },
+            },
+            "401": { description: "Missing or invalid bearer token" },
+            ...(scoped
+                ? { "403": { description: "Key lacks the permission / is bound to another app" } }
+                : {}),
+            ...(write
+                ? {
+                    "405": {
+                        description: "Method not allowed on this resource (see the `Allow` header)",
+                    },
+                    "409": { description: "Conflict (already a member, last admin, slug taken, …)" },
+                }
+                : {}),
+            ...(def.input ? { "422": { description: "Body failed validation" } } : {}),
+        },
+    };
+}
+export function buildOpenApiDocument(input) {
+    const paths = {};
+    for (const key of Object.keys(operations)) {
+        const [method, path] = key.split(" ");
+        const def = lookup(method, path);
+        if (!def)
+            continue;
+        paths[path] ??= {};
+        paths[path][method] = operationObject(method, path, def);
+    }
+    return {
+        openapi: "3.1.0",
+        info: {
+            title: "willy.im IdP — Management API",
+            version: "1.0.0",
+            description: DESCRIPTION,
+        },
+        servers: [{ url: input.baseUrl }],
+        components: {
+            securitySchemes: {
+                bearerAuth: {
+                    type: "http",
+                    scheme: "bearer",
+                    description: "Superadmin ADMIN_API_TOKEN or a scoped API key (wim_…).",
+                },
+            },
+        },
+        paths,
+    };
+}

package/dist/src/schemas/operations.d.ts

@@ -0,0 +1,297 @@
+/**
+ * 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";
+export type HttpMethod = "get" | "post" | "patch" | "delete" | "put";
+/** A query parameter, as the document describes it. Path params are inferred. */
+export type QueryParam = {
+    name: string;
+    description?: string;
+    required?: boolean;
+};
+export type OperationDef = {
+    summary: string;
+    /**
+     * The scoped-key permission this operation needs. Absent means superadmin
+     * only — the cross-app list endpoints.
+     */
+    permission?: string;
+    description?: string;
+    query?: readonly QueryParam[];
+    /** Path-parameter descriptions, keyed by name. Purely documentation. */
+    params?: Readonly<Record<string, string>>;
+    input?: z.ZodType;
+    successCode: "200" | "201";
+    success: z.ZodType;
+};
+export declare const operations: {
+    readonly "get /api/v1/applications": {
+        readonly summary: "List registered applications";
+        readonly successCode: "200";
+        readonly success: z.ZodObject<{
+            applications: z.ZodArray<z.ZodObject<{
+                clientId: z.ZodString;
+                name: z.ZodNullable<z.ZodString>;
+                app: z.ZodNullable<z.ZodString>;
+                redirectUris: z.ZodArray<z.ZodString>;
+                disabled: z.ZodBoolean;
+                createdAt: z.ZodString;
+            }, z.core.$strip>>;
+        }, z.core.$strip>;
+    };
+    readonly "get /api/v1/users": {
+        readonly summary: "List users";
+        readonly successCode: "200";
+        readonly success: z.ZodObject<{
+            users: z.ZodArray<z.ZodObject<{
+                id: z.ZodString;
+                email: z.ZodString;
+                name: z.ZodNullable<z.ZodString>;
+                emailVerified: z.ZodBoolean;
+                createdAt: z.ZodString;
+            }, z.core.$strip>>;
+        }, z.core.$strip>;
+    };
+    readonly "get /api/v1/workspaces": {
+        readonly summary: "List workspaces";
+        readonly successCode: "200";
+        readonly success: z.ZodObject<{
+            workspaces: z.ZodArray<z.ZodObject<{
+                id: z.ZodString;
+                name: z.ZodString;
+                slug: z.ZodString;
+                applicationId: z.ZodNullable<z.ZodString>;
+                createdAt: z.ZodString;
+            }, z.core.$strip>>;
+        }, z.core.$strip>;
+    };
+    readonly "get /api/v1/apps/{app}/members": {
+        readonly summary: "List app members";
+        readonly permission: "member:read";
+        readonly params: {
+            readonly app: "Application key (oauth_client.metadata.app).";
+        };
+        readonly successCode: "200";
+        readonly success: z.ZodObject<{
+            members: z.ZodArray<z.ZodObject<{
+                userId: z.ZodString;
+                email: z.ZodString;
+                name: z.ZodNullable<z.ZodString>;
+                role: z.ZodEnum<{
+                    admin: "admin";
+                    member: "member";
+                }>;
+                permissions: z.ZodArray<z.ZodString>;
+            }, z.core.$strip>>;
+        }, z.core.$strip>;
+    };
+    readonly "post /api/v1/apps/{app}/members": {
+        readonly summary: "Add or invite a member";
+        readonly permission: "member:invite";
+        readonly params: {
+            readonly app: "Application key (oauth_client.metadata.app).";
+        };
+        readonly input: z.ZodObject<{
+            email: z.ZodString;
+            role: z.ZodDefault<z.ZodEnum<{
+                admin: "admin";
+                member: "member";
+            }>>;
+            permissions: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        }, z.core.$strip>;
+        readonly successCode: "201";
+        readonly success: z.ZodObject<{
+            result: z.ZodEnum<{
+                added: "added";
+                invited: "invited";
+            }>;
+        }, z.core.$strip>;
+    };
+    readonly "patch /api/v1/apps/{app}/members/{userId}": {
+        readonly summary: "Update a member's role + permissions";
+        readonly permission: "member:manage";
+        readonly params: {
+            readonly app: "Application key (oauth_client.metadata.app).";
+        };
+        readonly input: z.ZodObject<{
+            role: z.ZodEnum<{
+                admin: "admin";
+                member: "member";
+            }>;
+            permissions: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        }, z.core.$strip>;
+        readonly successCode: "200";
+        readonly success: z.ZodObject<{
+            ok: z.ZodLiteral<true>;
+        }, z.core.$strip>;
+    };
+    readonly "delete /api/v1/apps/{app}/members/{userId}": {
+        readonly summary: "Remove a member";
+        readonly permission: "member:manage";
+        readonly params: {
+            readonly app: "Application key (oauth_client.metadata.app).";
+        };
+        readonly successCode: "200";
+        readonly success: z.ZodObject<{
+            ok: z.ZodLiteral<true>;
+        }, z.core.$strip>;
+    };
+    readonly "get /api/v1/apps/{app}/workspaces": {
+        readonly summary: "List app workspaces";
+        readonly permission: "workspace:read";
+        readonly params: {
+            readonly app: "Application key (oauth_client.metadata.app).";
+        };
+        readonly successCode: "200";
+        readonly success: z.ZodObject<{
+            workspaces: z.ZodArray<z.ZodObject<{
+                id: z.ZodString;
+                name: z.ZodString;
+                slug: z.ZodString;
+                applicationId: z.ZodNullable<z.ZodString>;
+                createdAt: z.ZodString;
+            }, z.core.$strip>>;
+        }, z.core.$strip>;
+    };
+    readonly "post /api/v1/apps/{app}/workspaces": {
+        readonly summary: "Create a workspace";
+        readonly permission: "workspace:create";
+        readonly params: {
+            readonly app: "Application key (oauth_client.metadata.app).";
+        };
+        readonly input: z.ZodObject<{
+            name: z.ZodString;
+            slug: z.ZodString;
+        }, z.core.$strip>;
+        readonly successCode: "201";
+        readonly success: z.ZodObject<{
+            id: z.ZodString;
+            name: z.ZodString;
+            slug: z.ZodString;
+        }, z.core.$strip>;
+    };
+    readonly "get /api/v1/apps/{app}/user-keys": {
+        readonly summary: "List end-user API keys";
+        readonly permission: "userkey:read";
+        readonly params: {
+            readonly app: "Application key (oauth_client.metadata.app).";
+        };
+        readonly query: readonly [{
+            readonly name: "userId";
+            readonly description: "Only keys owned by this user.";
+        }, {
+            readonly name: "workspaceId";
+            readonly description: "Only keys bound to this workspace.";
+        }];
+        readonly successCode: "200";
+        readonly success: z.ZodObject<{
+            keys: z.ZodArray<z.ZodObject<{
+                id: z.ZodString;
+                userId: z.ZodString;
+                workspaceId: z.ZodNullable<z.ZodString>;
+                name: z.ZodString;
+                prefix: z.ZodString;
+                scopes: z.ZodArray<z.ZodString>;
+                status: z.ZodEnum<{
+                    active: "active";
+                    expired: "expired";
+                    revoked: "revoked";
+                }>;
+                createdAt: z.ZodString;
+                lastUsedAt: z.ZodNullable<z.ZodString>;
+                expiresAt: z.ZodNullable<z.ZodString>;
+            }, z.core.$strip>>;
+        }, z.core.$strip>;
+    };
+    readonly "post /api/v1/apps/{app}/user-keys": {
+        readonly summary: "Mint an end-user API key (plaintext returned once)";
+        readonly permission: "userkey:create";
+        readonly params: {
+            readonly app: "Application key (oauth_client.metadata.app).";
+        };
+        readonly input: z.ZodObject<{
+            userId: z.ZodString;
+            name: z.ZodString;
+            scopes: z.ZodDefault<z.ZodArray<z.ZodString>>;
+            workspaceId: z.ZodOptional<z.ZodString>;
+            expiresAt: z.ZodOptional<z.ZodISODateTime>;
+        }, z.core.$strip>;
+        readonly successCode: "201";
+        readonly success: z.ZodObject<{
+            id: z.ZodString;
+            token: z.ZodString;
+            prefix: z.ZodString;
+        }, z.core.$strip>;
+    };
+    readonly "post /api/v1/apps/{app}/user-keys/validate": {
+        readonly summary: "Validate a presented end-user key (200 + valid discriminator)";
+        readonly permission: "userkey:validate";
+        readonly params: {
+            readonly app: "Application key (oauth_client.metadata.app).";
+        };
+        readonly input: z.ZodObject<{
+            token: z.ZodString;
+        }, z.core.$strip>;
+        readonly successCode: "200";
+        readonly success: z.ZodUnion<readonly [z.ZodObject<{
+            valid: z.ZodLiteral<true>;
+            keyId: z.ZodString;
+            userId: z.ZodString;
+            workspaceId: z.ZodNullable<z.ZodString>;
+            scopes: z.ZodArray<z.ZodString>;
+            name: z.ZodString;
+        }, z.core.$strip>, z.ZodObject<{
+            valid: z.ZodLiteral<false>;
+            reason: z.ZodEnum<{
+                expired: "expired";
+                revoked: "revoked";
+                not_found: "not_found";
+            }>;
+        }, z.core.$strip>]>;
+    };
+    readonly "delete /api/v1/apps/{app}/user-keys/{id}": {
+        readonly summary: "Revoke an end-user API key (idempotent)";
+        readonly permission: "userkey:revoke";
+        readonly params: {
+            readonly app: "Application key (oauth_client.metadata.app).";
+        };
+        readonly successCode: "200";
+        readonly success: z.ZodObject<{
+            ok: z.ZodLiteral<true>;
+        }, z.core.$strip>;
+    };
+    readonly "get /api/v1/apps/{app}/audit": {
+        readonly summary: "List recent audit entries";
+        readonly permission: "audit:read";
+        readonly params: {
+            readonly app: "Application key (oauth_client.metadata.app).";
+        };
+        readonly successCode: "200";
+        readonly success: z.ZodObject<{
+            entries: z.ZodArray<z.ZodObject<{
+                id: z.ZodNumber;
+                tableName: z.ZodString;
+                operation: z.ZodString;
+                rowId: z.ZodNullable<z.ZodString>;
+                userId: z.ZodNullable<z.ZodString>;
+                actor: z.ZodNullable<z.ZodString>;
+                createdAt: z.ZodString;
+            }, z.core.$strip>>;
+        }, z.core.$strip>;
+    };
+};
+export type Operations = typeof operations;
+export type OperationKey = keyof Operations;
+/** `"get /api/v1/users"` -> the paths that declare that method. */
+export type PathsFor<M extends HttpMethod> = OperationKey extends infer K ? K extends `${M} ${infer P}` ? P : never : never;
+export type OperationFor<M extends HttpMethod, P extends string> = `${M} ${P}` extends OperationKey ? Operations[`${M} ${P}`] : never;
+/** Path parameters read straight off the path template — `{app}`, `{userId}`. */
+export type PathParamNames<P extends string> = P extends `${string}{${infer Name}}${infer Rest}` ? Name | PathParamNames<Rest> : never;
+export declare function lookup(method: string, path: string): OperationDef | undefined;
+//# sourceMappingURL=operations.d.ts.map

package/dist/src/schemas/operations.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"operations.d.ts","sourceRoot":"","sources":["../../../src/schemas/operations.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAqBvB,MAAM,MAAM,UAAU,GAAG,KAAK,GAAG,MAAM,GAAG,OAAO,GAAG,QAAQ,GAAG,KAAK,CAAA;AAEpE,iFAAiF;AACjF,MAAM,MAAM,UAAU,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,OAAO,CAAA;CAAE,CAAA;AAEnF,MAAM,MAAM,YAAY,GAAG;IACzB,OAAO,EAAE,MAAM,CAAA;IACf;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,KAAK,CAAC,EAAE,SAAS,UAAU,EAAE,CAAA;IAC7B,wEAAwE;IACxE,MAAM,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAA;IACzC,KAAK,CAAC,EAAE,CAAC,CAAC,OAAO,CAAA;IACjB,WAAW,EAAE,KAAK,GAAG,KAAK,CAAA;IAC1B,OAAO,EAAE,CAAC,CAAC,OAAO,CAAA;CACnB,CAAA;AAID,eAAO,MAAM,UAAU;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA0G0B,CAAA;AAEjD,MAAM,MAAM,UAAU,GAAG,OAAO,UAAU,CAAA;AAC1C,MAAM,MAAM,YAAY,GAAG,MAAM,UAAU,CAAA;AAE3C,mEAAmE;AACnE,MAAM,MAAM,QAAQ,CAAC,CAAC,SAAS,UAAU,IAAI,YAAY,SAAS,MAAM,CAAC,GACrE,CAAC,SAAS,GAAG,CAAC,IAAI,MAAM,CAAC,EAAE,GACzB,CAAC,GACD,KAAK,GACP,KAAK,CAAA;AAET,MAAM,MAAM,YAAY,CAAC,CAAC,SAAS,UAAU,EAAE,CAAC,SAAS,MAAM,IAAI,GAAG,CAAC,IAAI,CAAC,EAAE,SAAS,YAAY,GAC/F,UAAU,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,GACvB,KAAK,CAAA;AAET,iFAAiF;AACjF,MAAM,MAAM,cAAc,CAAC,CAAC,SAAS,MAAM,IAAI,CAAC,SAAS,GAAG,MAAM,IAAI,MAAM,IAAI,IAAI,MAAM,IAAI,EAAE,GAC5F,IAAI,GAAG,cAAc,CAAC,IAAI,CAAC,GAC3B,KAAK,CAAA;AAET,wBAAgB,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,YAAY,GAAG,SAAS,CAE7E"}

package/dist/src/schemas/operations.js

@@ -0,0 +1,118 @@
+/**
+ * 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 { ApplicationListSchema, AuditListSchema, CreateUserApiKeyInput, CreateWorkspaceInput, InviteMemberInput, InviteMemberResult, MemberListSchema, OkSchema, UpdateMemberInput, UserApiKeyCreatedSchema, UserApiKeyListSchema, UserApiKeyValidationSchema, UserListSchema, ValidateUserApiKeyInput, WorkspaceCreatedSchema, WorkspaceListSchema, } from "./index.js";
+const APP_PARAM = { app: "Application key (oauth_client.metadata.app)." };
+export const operations = {
+    "get /api/v1/applications": {
+        summary: "List registered applications",
+        successCode: "200",
+        success: ApplicationListSchema,
+    },
+    "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);