@browserlessapi/inferlo 0.6.0 → 0.8.0

package/dist/model.d.ts

@@ -4,27 +4,43 @@ export type SystemShape = {
     createdAt: Schema<Date, Date | string>;
     updatedAt: Schema<Date, Date | string>;
 };
-export declare class Model<N extends string = string, S extends Shape = Shape> {
+/** Options of model(). */
+export interface ModelOptions {
+    /**
+     * true: the table belongs to tenants (organisations, workspaces, customers). Every row gets a
+     * tenantId column, and ctx.db filters every query by and stamps every insert with the current
+     * tenant (auth.tenant(user), default user.tenantId). Unique fields are unique per tenant.
+     */
+    tenant?: boolean;
+}
+/** Longest tenant id Inferlo accepts. */
+export declare const MAX_TENANT_ID = 200;
+export type TenantShape = {
+    tenantId: Schema<string>;
+};
+export declare class Model<N extends string = string, S extends Shape = Shape, T extends boolean = false> {
     /** Table name, also the property name on `db` (db.tickets). */
     readonly name: N;
     /** Fields you defined. */
     readonly fields: S;
-    /** Full row schema including id, createdAt and updatedAt. */
-    readonly row: ObjectSchema<SystemShape & S>;
+    /** Full row schema including id, createdAt and updatedAt (and tenantId on tenant-scoped models). */
+    readonly row: ObjectSchema<SystemShape & S & (T extends true ? TenantShape : {})>;
+    /** True when the model is tenant-scoped (model(name, fields, { tenant: true })). */
+    readonly tenant: T;
     /** Input schema for inserts. Fields with defaults or .optional() may be left out. */
     readonly create: ObjectSchema<S>;
     /** Input schema for updates. Every field optional. */
     readonly update: ObjectSchema<PartialShape<S>>;
     /** Type-only: the row type. Prefer Row<typeof Model>. */
-    readonly $row: ShapeOutput<SystemShape & S>;
+    readonly $row: ShapeOutput<SystemShape & S & (T extends true ? TenantShape : {})>;
     readonly $create: ShapeInput<S>;
-    constructor(name: N, fields: S);
+    constructor(name: N, fields: S, options?: ModelOptions);
     /** Input schema with only some fields, e.g. for a route body: Ticket.pick("title", "body"). */
     pick<K extends keyof S & string>(...keys: K[]): ObjectSchema<Pick<S, K>>;
     /** Input schema without some fields, e.g. Ticket.omit("ownerId"). */
     omit<K extends keyof S & string>(...keys: K[]): ObjectSchema<Omit<S, K>>;
 }
-export type AnyModel = Model<string, any>;
+export type AnyModel = Model<string, any, boolean>;
 /** Row type of a model: Row<typeof Ticket>. */
 export type Row<M extends AnyModel> = M["$row"];
 /** Insert input type of a model. */
@@ -32,5 +48,6 @@ export type CreateInput<M extends AnyModel> = M["$create"];
 /** Update input type of a model. */
 export type UpdateInput<M extends AnyModel> = Partial<M["$create"]>;
 export declare function model<const N extends string, S extends Shape>(name: N, fields: S): Model<N, S>;
+export declare function model<const N extends string, S extends Shape, const O extends ModelOptions>(name: N, fields: S, options: O): Model<N, S, O["tenant"] extends true ? true : false>;
 /** camelCase field name to snake_case column name. */
 export declare function columnName(field: string): string;

package/dist/model.js

@@ -8,38 +8,68 @@
  *   })
  *
  * Every model gets id (uuid), createdAt and updatedAt automatically.
+ *
+ * Tenant-scoped models (multi-tenant apps) also get tenantId, set from the signed-in user:
+ *
+ *   export const Ticket = model("tickets", { title: t.string() }, { tenant: true })
  */
 import { InferloError } from "./errors.js";
-import { ObjectSchema, Schema, t } from "./schema.js";
+import { ObjectSchema, Schema, containsFile, t } from "./schema.js";
 const TABLE_NAME = /^[a-z][a-z0-9_]{0,62}$/;
 const FIELD_NAME = /^[a-zA-Z][a-zA-Z0-9]{0,62}$/;
 const RESERVED = new Set(["id", "createdAt", "updatedAt"]);
 function system(schema, kind) {
     return new Schema({ ...schema.def, system: kind });
 }
+/** Longest tenant id Inferlo accepts. */
+export const MAX_TENANT_ID = 200;
 export class Model {
     /** Table name, also the property name on `db` (db.tickets). */
     name;
     /** Fields you defined. */
     fields;
-    /** Full row schema including id, createdAt and updatedAt. */
+    /** Full row schema including id, createdAt and updatedAt (and tenantId on tenant-scoped models). */
     row;
+    /** True when the model is tenant-scoped (model(name, fields, { tenant: true })). */
+    tenant;
     /** Input schema for inserts. Fields with defaults or .optional() may be left out. */
     create;
     /** Input schema for updates. Every field optional. */
     update;
-    constructor(name, fields) {
+    constructor(name, fields, options = {}) {
         if (!TABLE_NAME.test(name)) {
             throw new InferloError("IL4005", `Model name "${name}" is not a valid table name.`, {
                 fix: 'Use lowercase letters, digits and underscores, starting with a letter, e.g. model("support_tickets", {...}).',
             });
         }
+        if (options === null || typeof options !== "object" || Array.isArray(options)) {
+            throw new InferloError("IL4026", `The options of model "${name}" must be an object.`, { fix: `Pass model("${name}", { ...fields }, { tenant: true }), or leave the options out.` });
+        }
+        for (const key of Object.keys(options)) {
+            if (key !== "tenant") {
+                throw new InferloError("IL4026", `Unknown option "${key}" in model "${name}".`, { fix: "model() takes one option: { tenant: true }." });
+            }
+        }
+        if (options.tenant !== undefined && typeof options.tenant !== "boolean") {
+            throw new InferloError("IL4026", `The tenant option of model "${name}" must be true or false.`, { fix: `Use model("${name}", { ...fields }, { tenant: true }).` });
+        }
+        const tenant = options.tenant === true;
         for (const key of Object.keys(fields)) {
+            if (tenant && key === "tenantId") {
+                throw new InferloError("IL4006", `Model "${name}" defines "tenantId", which Inferlo adds to tenant-scoped models.`, {
+                    fix: 'Remove "tenantId" from the model. With { tenant: true } every row already has tenantId, set from the current tenant.',
+                });
+            }
             if (RESERVED.has(key)) {
                 throw new InferloError("IL4006", `Model "${name}" defines "${key}", which Inferlo adds automatically.`, {
                     fix: `Remove "${key}" from the model. Every model already has id, createdAt and updatedAt.`,
                 });
             }
+            if (containsFile(fields[key])) {
+                throw new InferloError("IL1004", `Field "${name}.${key}" uses t.file(), which only works in route bodies.`, {
+                    fix: "Accept the upload in a route body (body: t.object({ file: t.file() })), store the file elsewhere, and keep its key or URL in a t.string() field of the model.",
+                });
+            }
             if (!FIELD_NAME.test(key)) {
                 throw new InferloError("IL4005", `Field "${name}.${key}" is not a valid field name.`, {
                     fix: "Use camelCase letters and digits, e.g. ownerId. Inferlo stores it as owner_id.",
@@ -47,15 +77,19 @@ export class Model {
             }
         }
         this.name = name;
-        this.fields = fields;
+        this.tenant = tenant;
         this.create = t.object(fields);
         this.update = this.create.partial();
+        // tenantId is a column like the others for the adapters, migrations and describe(), but never input.
+        this.fields = (tenant
+            ? { ...fields, tenantId: system(t.string().min(1).max(MAX_TENANT_ID).index().describe("Set automatically from the current tenant"), "tenantId") }
+            : fields);
         const systemShape = {
             id: system(t.uuid(), "id"),
             createdAt: system(t.date(), "createdAt"),
             updatedAt: system(t.date(), "updatedAt"),
         };
-        this.row = t.object({ ...systemShape, ...fields });
+        this.row = t.object({ ...systemShape, ...this.fields });
     }
     /** Input schema with only some fields, e.g. for a route body: Ticket.pick("title", "body"). */
     pick(...keys) {
@@ -66,8 +100,8 @@ export class Model {
         return this.create.omit(...keys);
     }
 }
-export function model(name, fields) {
-    return new Model(name, fields);
+export function model(name, fields, options) {
+    return new Model(name, fields, options);
 }
 /** camelCase field name to snake_case column name. */
 export function columnName(field) {

package/dist/model.js.map

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

package/dist/oidc.d.ts

@@ -0,0 +1,70 @@
+import { type JwtClaims } from "./jwt.ts";
+import { type AppDb, type RouteDef } from "./route.ts";
+import type { Sessions } from "./sessions.ts";
+/** The claims of a verified ID token. Providers add their own (email, email_verified, name, groups, tid, hd, ...). */
+export interface OidcClaims extends JwtClaims {
+    nonce?: string;
+    email?: string;
+    email_verified?: boolean;
+    name?: string;
+}
+/** The provider's answer to the code exchange. */
+export interface OidcTokens {
+    idToken: string;
+    /** For calling the provider's APIs (userinfo, Microsoft Graph, ...); never stored by Inferlo. */
+    accessToken?: string;
+    refreshToken?: string;
+    /** Seconds until the access token expires, as the provider says. */
+    expiresIn?: number;
+    scope?: string;
+}
+export interface OidcOptions {
+    /** The provider's issuer exactly as its OpenID configuration names it, such as "https://acme.okta.com". https, except on localhost. */
+    issuer: string;
+    /** The app's client id at the provider. */
+    clientId: string;
+    /** The app's client secret (keep it in config({ secrets })). Leave it out for a public client, which PKCE protects. */
+    clientSecret?: string;
+    /** The sessions() the sign-in ends in; also the app's auth: createApp({ auth: session }). */
+    session: Sessions;
+    /**
+     * The id of the app's user for a verified ID token (find or create the user), or null to refuse the sign-in
+     * (403 IL3011). Check claims.email_verified before trusting claims.email.
+     */
+    userId: (claims: OidcClaims, ctx: {
+        db: AppDb;
+        req: Request;
+        tokens: OidcTokens;
+    }) => string | null | undefined | Promise<string | null | undefined>;
+    /** Where the provider sends the browser back, registered at the provider. Default: <the request's origin><basePath>/callback. */
+    redirectUri?: string;
+    /** Scopes to ask for. Default ["openid", "email", "profile"]; "openid" is always sent. */
+    scopes?: string[];
+    /** Where the login, callback and logout routes are. Default "/auth": GET /auth/login, GET /auth/callback and POST /auth/logout. */
+    basePath?: string;
+    /**
+     * Extra parameters for every sign-in at the provider, such as { prompt: "select_account" }, Google's
+     * { hd: "acme.com" } or Entra ID's { domain_hint: "acme.com" }. The flow's own parameters cannot be changed.
+     */
+    authorizationParams?: Record<string, string>;
+    /** Where the provider sends the browser after signing out, registered at the provider. Default: <the request's origin>/. */
+    postLogoutRedirectUri?: string;
+}
+/** routes: [sso] adds the two routes; oidcLogin starts a sign-in, oidcCallback finishes it. */
+export type Oidc = {
+    /** GET <basePath>/login?returnTo=/path: sends the browser to the provider. */
+    oidcLogin: RouteDef;
+    /** GET <basePath>/callback: the redirect URI registered at the provider. */
+    oidcCallback: RouteDef;
+    /** POST <basePath>/logout (with the session's _csrf field): ends the session, then signs out at the provider. */
+    oidcLogout: RouteDef;
+    /** The login route's path, for links: <a href={sso.loginPath}>. */
+    loginPath: string;
+    /** The logout route's path, for a form: <form method="post" action={sso.logoutPath}>. */
+    logoutPath: string;
+};
+/**
+ * OpenID Connect sign-in for browser apps: routes: [sso] with sso = oidc({ issuer, clientId, clientSecret,
+ * session, userId }). The sign-in ends in the session's cookie.
+ */
+export declare function oidc(options: OidcOptions): Oidc;

package/dist/oidc.js

@@ -0,0 +1,379 @@
+/**
+ * Single sign-on for browser apps with OpenID Connect (Okta, Microsoft Entra ID, Google, Auth0, Keycloak, Ping,
+ * OneLogin, JumpCloud, Authentik, Zitadel and any other OpenID provider): the authorization code flow with PKCE,
+ * state and nonce, ending in a sessions() cookie.
+ *
+ *   export const session = sessions({ secret: settings.SESSION_SECRET, user: ({ userId }, { db }) => db.users.find(userId) });
+ *   export const sso = oidc({
+ *     issuer: "https://acme.okta.com",
+ *     clientId: settings.OIDC_CLIENT_ID,
+ *     clientSecret: settings.OIDC_CLIENT_SECRET,
+ *     session,
+ *     userId: async (claims, { db }) => (await db.users.findOne({ email: claims.email }))?.id ?? null,
+ *   });
+ *   createApp({ auth: session, routes: [notes, sso] });
+ *
+ * GET /auth/login (?returnTo=/path) sends the browser to the provider; GET /auth/callback checks what comes back
+ * (state, the code exchanged with the PKCE verifier, the ID token's signature, issuer, audience, expiry and nonce),
+ * asks userId(claims) which user signs in, starts the session and sends the browser back. POST /auth/logout ends the
+ * session and signs the user out at the provider too (RP-initiated logout). No runtime dependencies.
+ */
+import { safeEqual } from "./auth.js";
+import { InferloError } from "./errors.js";
+import { ASYMMETRIC, createJwtVerifier, isLocal } from "./jwt.js";
+import { route } from "./route.js";
+const OPTIONS = ["issuer", "clientId", "clientSecret", "session", "userId", "redirectUri", "scopes", "basePath", "authorizationParams", "postLogoutRedirectUri"];
+/** The parameters oidc() sets itself, which authorizationParams cannot change. */
+const RESERVED_PARAMS = ["response_type", "client_id", "redirect_uri", "scope", "state", "nonce", "code_challenge", "code_challenge_method", "response_mode", "request", "request_uri"];
+/** The prompt values a login link may ask for with ?prompt= (OpenID Connect Core and Initiating User Registration). */
+const PROMPTS = ["none", "login", "consent", "select_account", "create"];
+/** ID tokens up to this size are kept for signing out at the provider; larger ones would not fit in a cookie. */
+const MAX_ID_TOKEN_COOKIE = 3500;
+/** How long the ID token is kept for signing out (the longest a sessions() cookie can last). */
+const ID_TOKEN_COOKIE_SECONDS = 400 * 86_400;
+const FETCH_TIMEOUT = 5000;
+const DISCOVERY_CACHE_MS = 600_000;
+const PENDING_MS = 600_000;
+const fix = 'Use oidc({ issuer: "https://login.example.com", clientId: settings.OIDC_CLIENT_ID, clientSecret: settings.OIDC_CLIENT_SECRET, session, userId: (claims, { db }) => ... }) with the issuer, client id and secret your identity provider shows for this app.';
+function invalid(message, fixText = fix) {
+    return new InferloError("IL6047", message, { fix: fixText });
+}
+function failed(reason) {
+    return new InferloError("IL3009", `The sign-in could not be completed: ${reason}.`, {
+        status: 400,
+        fix: "Start the sign-in again from the app's login link, in the same browser. If it keeps failing, check the app's OpenID Connect settings (issuer, client id, redirect URI) at the provider.",
+    });
+}
+function unreachable(what, cause) {
+    return new InferloError("IL3010", `The identity provider could not be used: ${what}.`, {
+        status: 502,
+        fix: `Check that the issuer, client id and client secret are right and that the provider is reachable from the server (${cause instanceof Error ? cause.message : String(cause)}).`,
+    });
+}
+function httpsUrl(value, what) {
+    let url;
+    try {
+        url = new URL(String(value));
+    }
+    catch {
+        throw invalid(`oidc() ${what} must be a URL, got ${JSON.stringify(value)}.`);
+    }
+    if (url.protocol !== "https:" && !(url.protocol === "http:" && isLocal(url))) {
+        throw invalid(`oidc() ${what} must use https (plain http only on localhost), got ${JSON.stringify(value)}.`);
+    }
+    return url;
+}
+function base64url(bytes) {
+    let binary = "";
+    for (const byte of bytes)
+        binary += String.fromCharCode(byte);
+    return btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+function random() {
+    return base64url(crypto.getRandomValues(new Uint8Array(32)));
+}
+/** A path on this app to return to after the sign-in, or "/": never another site (open redirect). */
+function safeReturnTo(value) {
+    if (typeof value !== "string" || !value.startsWith("/") || value.startsWith("//") || value.startsWith("/\\") || value.length > 2000)
+        return "/";
+    if (/[\u0000-\u001f\u007f\\]/.test(value))
+        return "/";
+    return value;
+}
+function readCookie(header, name) {
+    if (!header)
+        return undefined;
+    for (const part of header.split(";")) {
+        const index = part.indexOf("=");
+        if (index !== -1 && part.slice(0, index).trim() === name)
+            return part.slice(index + 1).trim();
+    }
+    return undefined;
+}
+/**
+ * The short-lived cookie that carries state, nonce and the PKCE verifier from login to callback ("inferlo_oidc"),
+ * and the one that keeps the ID token for signing out at the provider ("inferlo_oidc_id").
+ */
+function cookieFor(url, base = "inferlo_oidc") {
+    const local = url.protocol === "http:" && isLocal(url);
+    // __Host- cookies cannot be set by subdomains or for other paths; browsers need Secure for them.
+    return local ? { name: base, attributes: "Path=/; HttpOnly; SameSite=Lax" } : { name: `__Host-${base}`, attributes: "Path=/; HttpOnly; Secure; SameSite=Lax" };
+}
+/** The iss claim of a JWT, without checking it (only to pick the provider an ID token came from). */
+function issuerOf(token) {
+    try {
+        const payload = token.split(".")[1] ?? "";
+        const claims = JSON.parse(new TextDecoder().decode(Uint8Array.from(atob(payload.replace(/-/g, "+").replace(/_/g, "/")), (c) => c.charCodeAt(0))));
+        return typeof claims.iss === "string" ? claims.iss : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * OpenID Connect sign-in for browser apps: routes: [sso] with sso = oidc({ issuer, clientId, clientSecret,
+ * session, userId }). The sign-in ends in the session's cookie.
+ */
+export function oidc(options) {
+    if (!options || typeof options !== "object" || Array.isArray(options))
+        throw invalid("oidc() needs { issuer, clientId, session, userId }.");
+    for (const key of Object.keys(options))
+        if (!OPTIONS.includes(key))
+            throw invalid(`oidc() has no option "${key}".`, `Use ${OPTIONS.join(", ")}.`);
+    if (typeof options.issuer !== "string" || !options.issuer)
+        throw invalid("oidc() needs the issuer: the provider's URL as its OpenID configuration names it.");
+    httpsUrl(options.issuer, "issuer");
+    if (typeof options.clientId !== "string" || !options.clientId)
+        throw invalid("oidc() needs the clientId the provider gave this app.");
+    if (options.clientSecret !== undefined && (typeof options.clientSecret !== "string" || !options.clientSecret)) {
+        throw invalid("oidc() clientSecret must be a non-empty string, or left out for a public client.", "Keep the client secret in config({ secrets }) and pass it as clientSecret.");
+    }
+    const session = options.session;
+    if (!session || typeof session !== "object" || typeof session.signIn !== "function" || typeof session.resolve !== "function") {
+        throw invalid("oidc() needs session: the sessions() the sign-in ends in.", "Pass session = sessions({ secret, user }), and use it as the app's auth too: createApp({ auth: session }).");
+    }
+    if (typeof options.userId !== "function")
+        throw invalid("oidc() needs userId(claims, { db }): the id of the app's user for a verified sign-in, or null to refuse it.");
+    const redirectUri = options.redirectUri === undefined ? undefined : httpsUrl(options.redirectUri, "redirectUri").href;
+    const scopes = options.scopes ?? ["openid", "email", "profile"];
+    if (!Array.isArray(scopes) || scopes.some((s) => typeof s !== "string" || !/^[\x21\x23-\x5b\x5d-\x7e]+$/.test(s))) {
+        throw invalid('oidc() scopes must be a list of scope names, such as ["openid", "email", "profile"].');
+    }
+    const scope = [...new Set(["openid", ...scopes])].join(" ");
+    const basePath = options.basePath ?? "/auth";
+    if (typeof basePath !== "string" || !/^\/[A-Za-z0-9._~\-/]*$/.test(basePath) || basePath.includes("//") || !basePath.replace(/\/+$/, "")) {
+        throw invalid(`oidc() basePath must be a path such as "/auth", got ${JSON.stringify(basePath)}.`);
+    }
+    const base = basePath.replace(/\/+$/, "");
+    const extraParams = options.authorizationParams ?? {};
+    if (!extraParams || typeof extraParams !== "object" || Array.isArray(extraParams)) {
+        throw invalid('oidc() authorizationParams must be an object of parameter names and string values, such as { prompt: "select_account" }.');
+    }
+    for (const [key, value] of Object.entries(extraParams)) {
+        if (RESERVED_PARAMS.includes(key)) {
+            throw invalid(`oidc() authorizationParams cannot set "${key}": oidc() sets it itself.`, `Leave "${key}" out of authorizationParams; use scopes for the scope and redirectUri for the redirect URI.`);
+        }
+        if (!/^[A-Za-z0-9_.-]{1,64}$/.test(key) || typeof value !== "string" || value.length > 1000 || /[\u0000-\u001f\u007f]/.test(value)) {
+            throw invalid(`oidc() authorizationParams.${key} must be a string of at most 1000 characters without control characters, under a parameter name such as "prompt" or "domain_hint".`);
+        }
+    }
+    const postLogoutRedirectUri = options.postLogoutRedirectUri === undefined ? undefined : httpsUrl(options.postLogoutRedirectUri, "postLogoutRedirectUri").href;
+    const { issuer, clientId, clientSecret } = options;
+    // The provider's OpenID configuration: fetched on first use, kept for 10 minutes, and kept longer while the
+    // provider cannot be reached.
+    let discovered;
+    let loading;
+    const loadDiscovery = async () => {
+        const url = `${issuer.replace(/\/+$/, "")}/.well-known/openid-configuration`;
+        const response = await fetch(url, { headers: { accept: "application/json" }, redirect: "error", signal: AbortSignal.timeout(FETCH_TIMEOUT) });
+        if (!response.ok)
+            throw new Error(`${url} answered ${response.status}`);
+        const body = (await response.json());
+        if (!body || typeof body !== "object")
+            throw new Error(`${url} did not answer a JSON object`);
+        if (body.issuer !== issuer)
+            throw new Error(`the OpenID configuration names the issuer ${JSON.stringify(body.issuer)}, not ${JSON.stringify(issuer)}`);
+        for (const key of ["authorization_endpoint", "token_endpoint", "jwks_uri"]) {
+            if (typeof body[key] !== "string")
+                throw new Error(`the OpenID configuration has no ${key}`);
+            httpsUrl(body[key], key);
+        }
+        if (body.end_session_endpoint !== undefined) {
+            if (typeof body.end_session_endpoint !== "string")
+                throw new Error("the OpenID configuration's end_session_endpoint is not a URL");
+            httpsUrl(body.end_session_endpoint, "end_session_endpoint");
+        }
+        return body;
+    };
+    const discovery = async () => {
+        if (discovered && Date.now() - discovered.at < DISCOVERY_CACHE_MS)
+            return discovered.value;
+        try {
+            loading ??= loadDiscovery().finally(() => (loading = undefined));
+            const value = await loading;
+            discovered = { value, at: Date.now() };
+            return value;
+        }
+        catch (error) {
+            if (discovered)
+                return discovered.value;
+            throw unreachable("its OpenID configuration could not be loaded", error);
+        }
+    };
+    const verifyIdToken = createJwtVerifier({
+        issuer,
+        audiences: [clientId],
+        allowed: ASYMMETRIC,
+        tolerance: 60,
+        cacheMs: DISCOVERY_CACHE_MS,
+        discoverJwksUrl: async () => (await discovery()).jwks_uri,
+    });
+    const callbackUrl = (url) => redirectUri ?? new URL(`${base}/callback`, url).href;
+    const start = async (ctx) => {
+        const config = await discovery();
+        const pending = { s: random(), n: random(), v: random(), r: safeReturnTo(ctx.url.searchParams.get("returnTo")), e: Date.now() + PENDING_MS };
+        const challenge = base64url(new Uint8Array(await crypto.subtle.digest("SHA-256", new TextEncoder().encode(pending.v))));
+        const target = new URL(config.authorization_endpoint);
+        target.searchParams.set("response_type", "code");
+        target.searchParams.set("client_id", clientId);
+        target.searchParams.set("redirect_uri", callbackUrl(ctx.url));
+        target.searchParams.set("scope", scope);
+        target.searchParams.set("state", pending.s);
+        target.searchParams.set("nonce", pending.n);
+        target.searchParams.set("code_challenge", challenge);
+        target.searchParams.set("code_challenge_method", "S256");
+        for (const [key, value] of Object.entries(extraParams))
+            target.searchParams.set(key, value);
+        // Per sign-in: ?loginHint= fills in the user's name at the provider, ?prompt= asks it to show the login or
+        // account picker again. Anything else in the query is ignored.
+        const loginHint = ctx.url.searchParams.get("loginHint");
+        if (loginHint && loginHint.length <= 256 && !/[\u0000-\u001f\u007f]/.test(loginHint))
+            target.searchParams.set("login_hint", loginHint);
+        const prompt = ctx.url.searchParams.get("prompt");
+        if (prompt && prompt.split(" ").every((p) => PROMPTS.includes(p)))
+            target.searchParams.set("prompt", prompt);
+        const cookie = cookieFor(ctx.url);
+        ctx.header("set-cookie", `${cookie.name}=${base64url(new TextEncoder().encode(JSON.stringify(pending)))}; ${cookie.attributes}; Max-Age=${PENDING_MS / 1000}`);
+        ctx.header("cache-control", "no-store");
+        return new Response(null, { status: 302, headers: { location: target.href } });
+    };
+    const exchange = async (config, code, verifier, url) => {
+        const form = new URLSearchParams({ grant_type: "authorization_code", code, redirect_uri: callbackUrl(url), code_verifier: verifier });
+        const headers = { "content-type": "application/x-www-form-urlencoded", accept: "application/json" };
+        const methods = Array.isArray(config.token_endpoint_auth_methods_supported) ? config.token_endpoint_auth_methods_supported : undefined;
+        if (clientSecret === undefined)
+            form.set("client_id", clientId);
+        else if (methods && !methods.includes("client_secret_basic") && methods.includes("client_secret_post")) {
+            form.set("client_id", clientId);
+            form.set("client_secret", clientSecret);
+        }
+        else {
+            // client_secret_basic, the default of OpenID Connect: both parts form-encoded first (RFC 6749, section 2.3.1).
+            const encode = (value) => encodeURIComponent(value).replace(/%20/g, "+");
+            headers.authorization = `Basic ${btoa(`${encode(clientId)}:${encode(clientSecret)}`)}`;
+        }
+        let response;
+        let body;
+        try {
+            response = await fetch(config.token_endpoint, { method: "POST", headers, body: form.toString(), redirect: "error", signal: AbortSignal.timeout(FETCH_TIMEOUT) });
+            body = (await response.json()) ?? {};
+        }
+        catch (error) {
+            throw unreachable("its token endpoint did not answer", error);
+        }
+        if (!response.ok) {
+            const error = typeof body.error === "string" && /^[\w.-]{1,64}$/.test(body.error) ? body.error : `status ${response.status}`;
+            // A wrong client id or secret is the app's configuration; anything else (a used or expired code) is this sign-in.
+            if (error === "invalid_client" || error === "unauthorized_client" || response.status >= 500)
+                throw unreachable(`its token endpoint refused the code exchange (${error})`, error);
+            throw failed(`the identity provider refused the code (${error})`);
+        }
+        if (typeof body.id_token !== "string")
+            throw failed("the identity provider sent no ID token (is the openid scope allowed for this app?)");
+        const tokens = { idToken: body.id_token };
+        if (typeof body.access_token === "string")
+            tokens.accessToken = body.access_token;
+        if (typeof body.refresh_token === "string")
+            tokens.refreshToken = body.refresh_token;
+        if (typeof body.expires_in === "number")
+            tokens.expiresIn = body.expires_in;
+        if (typeof body.scope === "string")
+            tokens.scope = body.scope;
+        return tokens;
+    };
+    const finish = async (ctx) => {
+        const params = ctx.url.searchParams;
+        const cookie = cookieFor(ctx.url);
+        // The pending sign-in is used once, whatever happens.
+        ctx.header("set-cookie", `${cookie.name}=; ${cookie.attributes}; Max-Age=0`);
+        ctx.header("cache-control", "no-store");
+        let pending;
+        try {
+            const raw = readCookie(ctx.req.headers.get("cookie"), cookie.name);
+            if (raw && raw.length < 4096) {
+                const parsed = JSON.parse(new TextDecoder().decode(Uint8Array.from(atob(raw.replace(/-/g, "+").replace(/_/g, "/")), (c) => c.charCodeAt(0))));
+                if (["s", "n", "v", "r"].every((k) => typeof parsed[k] === "string") && typeof parsed.e === "number")
+                    pending = parsed;
+            }
+        }
+        catch {
+            pending = undefined;
+        }
+        if (!pending || pending.e <= Date.now())
+            throw failed("it expired or was started in another browser");
+        const state = params.get("state");
+        if (!state || !safeEqual(state, pending.s))
+            throw failed("the state does not match the sign-in this browser started");
+        // RFC 9207: a provider that names itself in the redirect must be the configured one (mix-up attacks).
+        const iss = params.get("iss");
+        if (iss !== null && iss !== issuer)
+            throw failed("the answer came from another identity provider");
+        const error = params.get("error");
+        if (error !== null)
+            throw failed(`the identity provider answered ${/^[\w.-]{1,64}$/.test(error) ? error : "an error"}`);
+        const code = params.get("code");
+        if (!code)
+            throw failed("the identity provider sent no code");
+        const config = await discovery();
+        const tokens = await exchange(config, code, pending.v, ctx.url);
+        const claims = (await verifyIdToken(tokens.idToken));
+        if (!claims)
+            throw failed("the ID token is not valid for this app (signature, issuer, audience or expiry)");
+        if (typeof claims.nonce !== "string" || !safeEqual(claims.nonce, pending.n))
+            throw failed("the ID token's nonce does not match this sign-in");
+        if (Array.isArray(claims.aud) && claims.aud.length > 1 && claims.azp !== clientId)
+            throw failed("the ID token was issued to another app");
+        const userId = await options.userId(claims, { db: ctx.db, req: ctx.req, tokens });
+        if (userId === null || userId === undefined) {
+            throw new InferloError("IL3011", "This account may not sign in to the app.", { status: 403, fix: "Ask an administrator of the app for access." });
+        }
+        if (typeof userId !== "string" || !userId) {
+            throw new InferloError("IL6047", "oidc() userId must return the user's id as a non-empty string, or null to refuse the sign-in.", { fix: "Return the id of the app's user: userId: async (claims, { db }) => (await db.users.findOne({ email: claims.email }))?.id ?? null." });
+        }
+        await session.signIn(ctx, userId);
+        // The ID token is kept (HttpOnly) for signing out at the provider later, as id_token_hint.
+        const idCookie = cookieFor(ctx.url, "inferlo_oidc_id");
+        if (tokens.idToken.length <= MAX_ID_TOKEN_COOKIE && /^[\w-]+\.[\w-]+\.[\w-]*$/.test(tokens.idToken)) {
+            ctx.header("set-cookie", `${idCookie.name}=${tokens.idToken}; ${idCookie.attributes}; Max-Age=${ID_TOKEN_COOKIE_SECONDS}`);
+        }
+        else {
+            ctx.header("set-cookie", `${idCookie.name}=; ${idCookie.attributes}; Max-Age=0`);
+        }
+        return new Response(null, { status: 302, headers: { location: pending.r } });
+    };
+    const logout = async (ctx) => {
+        // A signed-in browser must send the session's CSRF token (IL3005), so other sites cannot sign users out.
+        await session.resolve(ctx.req, { db: ctx.db, url: ctx.url });
+        session.signOut(ctx);
+        const idCookie = cookieFor(ctx.url, "inferlo_oidc_id");
+        const idToken = readCookie(ctx.req.headers.get("cookie"), idCookie.name);
+        ctx.header("set-cookie", `${idCookie.name}=; ${idCookie.attributes}; Max-Age=0`);
+        ctx.header("cache-control", "no-store");
+        const afterLogout = postLogoutRedirectUri ?? new URL("/", ctx.url).href;
+        let endSession;
+        try {
+            endSession = (await discovery()).end_session_endpoint;
+        }
+        catch {
+            // The app's session is over; a provider that cannot be reached cannot end its own.
+            endSession = undefined;
+        }
+        if (!endSession)
+            return new Response(null, { status: 303, headers: { location: afterLogout } });
+        const target = new URL(endSession);
+        // Only an ID token this provider issued is sent back to it (with several providers, each has its basePath).
+        if (idToken && idToken.length <= MAX_ID_TOKEN_COOKIE && issuerOf(idToken) === issuer)
+            target.searchParams.set("id_token_hint", idToken);
+        target.searchParams.set("client_id", clientId);
+        target.searchParams.set("post_logout_redirect_uri", afterLogout);
+        return new Response(null, { status: 303, headers: { location: target.href } });
+    };
+    return {
+        oidcLogin: route.get(`${base}/login`, { auth: "public", summary: "Sign in with the identity provider (OpenID Connect)" }).handle(start),
+        oidcCallback: route.get(`${base}/callback`, { auth: "public", summary: "Finish the sign-in with the identity provider (OpenID Connect)" }).handle(finish),
+        oidcLogout: route.post(`${base}/logout`, { auth: "public", summary: "Sign out of the app and at the identity provider (OpenID Connect)" }).handle(logout),
+        loginPath: `${base}/login`,
+        logoutPath: `${base}/logout`,
+    };
+}
+//# sourceMappingURL=oidc.js.map