@broberg/sso 0.13.0 → 0.14.2

package/dist/hono.d.ts

@@ -1,391 +1,7 @@
 import * as hono_types from 'hono/types';
 import { Context, Hono, MiddlewareHandler } from 'hono';
-import { importJWK, JWTPayload } from 'jose';
-
-interface SsoConfig {
-    /** Broberg ID's origin, e.g. https://id.broberg.ai — the BARE origin. */
-    issuer: string;
-    /** The client id this app was registered under (administratively, in BID). */
-    clientId: string;
-    /** Exactly the redirect registered in BID. Exact match — one character decides. */
-    redirectUri: string;
-    /** Requested scopes. */
-    scopes: string[];
-    /** Signs the local session cookie. 32+ bytes of randomness. */
-    cookieSecret: string;
-    /** Local session cookie name. */
-    cookieName: string;
-    /**
-     * How long this app trusts its OWN session, in seconds.
-     *
-     * F084.7 decided the fleet's numbers: 7 days for a normal app, and 12 hours
-     * + 30 minutes of inactivity for anything holding personal or health data.
-     * The default here is the 7 days. An app handling patient data MUST set
-     * SSO_SESSION_MAX_AGE=43200 — the default is a normal-app default, not a
-     * safe-for-everything one.
-     */
-    sessionMaxAge: number;
-    /** Where to send the browser after a logout completes. */
-    postLogoutRedirectUri?: string;
-    /**
-     * Set ONLY by an app that can actually keep a secret — one whose callback
-     * runs on a server. Leave it unset for anything shipped to a browser; a
-     * secret in a static bundle is not a secret, and PKCE alone is the correct,
-     * fully standard design there.
-     *
-     * Setting it makes this a CONFIDENTIAL client: the secret is sent as
-     * `client_secret_post` (in the body), which is the method BID registers
-     * confidential clients with.
-     *
-     * IT DOES NOT RELAX PKCE. A secret proves which APP is asking; the PKCE
-     * verifier proves the request belongs to the browser that started the login.
-     * They defend against different attacks, so one is never an excuse to drop
-     * the other — and there is a test that fails if anyone makes it one.
-     */
-    clientSecret?: string;
-}
-
-/**
- * The signing-key cache.
- *
- * ── THE ONE BEHAVIOUR THIS FILE EXISTS FOR ────────────────────────────────
- *
- * It refetches on an UNKNOWN KEY ID, not on a timer (F084.4's constraint, and
- * it is the right one). An interval is a guess about when somebody else will
- * rotate their key; an unknown kid is the event itself. With an interval, the
- * window between "BID rotated" and "the interval elapsed" is a window where
- * every login in every app fails, and the length of that window is a number
- * nobody chose on purpose.
- *
- * ── AND THE PART AN OBVIOUS IMPLEMENTATION GETS WRONG ─────────────────────
- *
- * "Unknown kid ⇒ refetch" turns anyone who can send this app a token into
- * someone who can make it hammer BID: a stream of tokens with random kids is a
- * stream of fetches against the one service the whole fleet logs in through.
- * So a refetch is rate-limited by time. The cost of the floor is real and worth
- * stating: a rotation landing inside the cooldown makes logins fail for up to
- * that many milliseconds. Seconds of failure for one app beats a way to aim
- * traffic at BID from outside.
- *
- * ── TWO FAILURES, NOT ONE (components-F084.50) ───────────────────────────────────────
- *
- * Reported by helpdesk, measured in the published 0.1.0 dist: at process start
- * the key set is EMPTY, so the first verification fetches. If BID is down in
- * that second, NOTHING verifies for that app — not just new logins. A process
- * that has been running and has seen a kid survives the same outage untouched.
- *
- * The recovery was never the defect: `lastFetchAt` is set only on SUCCESS, so a
- * failed fetch does not block the next attempt and the cache self-heals the
- * moment BID answers again. The defect was that `getKey` threw the SAME error
- * for two states whose correct answers are opposites:
- *
- *   cannot reach the issuer    transient. Retry, or answer 503. The token may
- *                              well be perfectly good — we simply did not look.
- *   kid is not published       permanent. This token was not signed by us.
- *                              Reject it, 401, and do not retry.
- *
- * One error name for both is how a caller ends up rejecting a legitimate user
- * because a foreign service had a bad minute — or, worse, retrying a forgery.
- * Hence two subclasses. They BOTH extend JwksError, so a 0.1.0 consumer whose
- * catch tests `instanceof JwksError` keeps working across the upgrade.
- *
- * ── WHAT WE DELIBERATELY DID NOT DO ───────────────────────────────────────
- *
- * We do NOT persist the key set. A stored key set that survives a REVOCATION is
- * a worse failure than a login that is down for two minutes — helpdesk's own
- * point, and the reason `keys = body.keys` replaces rather than merges. Writing
- * the set to disk would reintroduce exactly what that line exists to prevent.
- */
-
-type SigningKey = Awaited<ReturnType<typeof importJWK>>;
-interface JwksCache {
-    /** Resolve a key for this kid, refetching once if it is unknown. */
-    getKey(kid: string, alg: string): Promise<SigningKey>;
-    /** How many times the remote key set has actually been fetched. */
-    readonly fetchCount: number;
-}
-
-/**
- * The core: framework-free, public-client OAuth 2.1 against Broberg ID.
- *
- * ── THIS PACKAGE IS A PUBLIC CLIENT. THERE IS NO CLIENT SECRET. ───────────
- *
- * Deliberate, and F084.4 AC#4 greps the published tarball to keep it that way.
- * PKCE alone carries the exchange. That is safe here for a reason worth stating
- * rather than assuming: BID matches redirect addresses EXACTLY (measured — one
- * trailing slash is refused), so the authorization code is delivered to this
- * app's own server and nowhere else. An attacker who knows the client id can
- * start a flow; they cannot receive its result.
- *
- * What it buys is the thing the card actually asks for: a secret that does not
- * exist cannot be committed, leaked in a log, copied into a second app, or left
- * behind in a repository someone later makes public.
- *
- * ── AND WHAT THIS PACKAGE MUST NEVER LEARN TO DO ──────────────────────────
- *
- * No passwords. No passkey registration. No social-provider keys. No email
- * verification. All of it lives in BID. A client that CAN do any of it is a
- * client somebody eventually uses to do it — and then the identity rules exist
- * in two places and drift.
- */
-
-interface Discovery {
-    /** What the issuer says it signs with. Absent on some providers. */
-    id_token_signing_alg_values_supported?: string[];
-    issuer: string;
-    authorization_endpoint: string;
-    token_endpoint: string;
-    jwks_uri: string;
-    userinfo_endpoint?: string;
-    end_session_endpoint?: string;
-}
-/** The signed-in user's own profile, as BID's GET /api/app/profile returns it. */
-interface BidProfile {
-    sub: string;
-    name: string | null;
-    picture: string | null;
-    email: string | null;
-    /** BID's own account page — mail, password, passkeys, 2FA and sessions live there. */
-    account_url: string;
-}
-/**
- * What `beginLogin` produces. Every field except `url` must survive the round
- * trip to BID and back — the adapter stores them in a short-lived cookie.
- *
- * They are NOT optional extras. `state` is what makes the callback provably the
- * answer to THIS request, and `nonce` is what stops a valid token minted for
- * some other login from being replayed into this one.
- */
-interface LoginStart {
-    url: string;
-    state: string;
-    codeVerifier: string;
-    nonce: string;
-}
-interface SsoClaims extends JWTPayload {
-    sub: string;
-    email?: string;
-    name?: string;
-    picture?: string;
-    email_verified?: boolean;
-}
-interface LoginResult {
-    claims: SsoClaims;
-    /**
-     * The claims in `claims` that came from the UNSIGNED userinfo response and
-     * not from the signed ID token (components-F084.51, since 0.8.0). Sorted; an
-     * empty list means everything in `claims` was signed (or userinfo was not
-     * reached). When both sources carry a claim, the signed token's value wins
-     * and the claim is not listed.
-     *
-     * On BID today this always contains "email" and "email_verified": the ID
-     * token does not carry them (measured by broberg-id, 20 Sep 2026). A decision
-     * that must rest on a signed identity binds on `claims.sub`, never on email.
-     */
-    unverifiedClaims: string[];
-    idToken: string;
-    accessToken?: string;
-    refreshToken?: string;
-    /** Seconds the access token lives, when BID said so (`expires_in`). */
-    expiresIn?: number;
-}
-/**
- * `prompt=none` asks BID to answer WITHOUT showing anything (components-F084.6).
- *
- * The delivery method decides whether it works, and this package only ever
- * produces a URL for a FULL TOP-LEVEL REDIRECT. It never returns anything an
- * app could put in a hidden iframe, because an iframe against the identity
- * provider is third-party context: Safari has blocked it for years and Chrome
- * is retiring it. That path works in testing on a Mac and fails for every user
- * on an iPhone — a failure that looks like "you are not logged in".
- */
-interface BeginLoginOptions {
-    prompt?: "none" | "login" | "consent" | "select_account";
-    /** Extra scopes for this one request, on top of the configured set. */
-    scopes?: string[];
-}
-interface SsoClient {
-    discovery(): Promise<Discovery>;
-    beginLogin(options?: BeginLoginOptions): Promise<LoginStart>;
-    completeLogin(input: {
-        params: URLSearchParams;
-        state: string;
-        codeVerifier: string;
-        nonce: string;
-    }): Promise<LoginResult>;
-    verifyIdToken(idToken: string, options?: {
-        nonce?: string;
-    }): Promise<SsoClaims>;
-    logoutUrl(options?: {
-        idTokenHint?: string;
-        postLogoutRedirectUri?: string;
-    }): Promise<string>;
-    /**
-     * Does this address belong to the signed-in user's BID account, and is it
-     * verified there? Asks BID's POST /api/app/address-ownership with the user's
-     * access token. Throws SsoError on anything that is not one of the three
-     * answers — see the implementation for why that must never become "unverified".
-     */
-    addressOwnership(accessToken: string, address: string): Promise<AddressOwnership>;
-    /**
-     * F095.1 — trade a refresh token for a new access token (`grant_type=refresh_token`).
-     * Throws SsoError on refusal; the message carries the status and BID's error
-     * code, never a token.
-     */
-    refreshTokens(refreshToken: string): Promise<{
-        accessToken: string;
-        refreshToken?: string;
-        expiresIn?: number;
-    }>;
-    /**
-     * Invite users to BID on behalf of this app (the app's OWN key, `bidk_…`).
-     * One result per email. Throws SsoError on anything BID did not clearly say.
-     */
-    inviteUsers(appKey: string, input: InviteUsersInput): Promise<InvitationResult[]>;
-    /**
-     * Where each user is in the move to BID. Throws SsoError on any state it does
-     * not know — never a silent "ready", which would switch off a user's old login
-     * while they cannot get in.
-     */
-    migrationStatus(appKey: string, emails: string[]): Promise<MigrationStatus>;
-    /**
-     * Verify an OIDC Back-Channel Logout token from BID («Log ud overalt»).
-     * Throws SsoError on anything that is not a valid, sub-only logout token.
-     */
-    verifyLogoutToken(token: string): Promise<LogoutToken>;
-    /**
-     * F095.2 — the signed-in user's own profile (scope `profile`), with the user's
-     * access token. Throws SsoAppApiError on any refusal.
-     */
-    getProfile(accessToken: string): Promise<BidProfile>;
-    /** F095.2 — change the user's own name (scope `profile:write`). Returns the new profile. */
-    updateProfile(accessToken: string, name: string): Promise<BidProfile>;
-    /**
-     * F095.2 — replace the user's picture (scope `profile:write`). Refuses more than
-     * MAX_AVATAR_BYTES or a type outside AVATAR_TYPES with SsoAvatarRejectedError
-     * BEFORE anything is sent.
-     */
-    uploadAvatar(accessToken: string, bytes: Uint8Array | ArrayBuffer, contentType: string): Promise<BidProfile>;
-    /** F095.2 — remove the user's picture (scope `profile:write`). */
-    removeAvatar(accessToken: string): Promise<BidProfile>;
-    /** Exposed for tests and for a health check; not needed in normal use. */
-    readonly jwks: JwksCache;
-}
-type AddressOwnership = "verified" | "unverified" | "not_on_account";
-type InvitationOutcome = "invited" | "already_invited" | "existing" | "invalid" | "too_soon" | "too_many_today" | "send_failed";
-interface InviteUsersInput {
-    customerName: string;
-    appUrl: string;
-    appName?: string;
-    switchDate?: string;
-    users: Array<{
-        email: string;
-        name: string;
-    }>;
-}
-interface InvitationResult {
-    email: string;
-    outcome: InvitationOutcome;
-    mailId?: string;
-    problem?: string;
-}
-type MigrationState = "ready" | "invited" | "expired" | "not_invited";
-interface MigrationStatus {
-    users: Array<{
-        email: string;
-        state: MigrationState;
-        expiresAt?: string;
-    }>;
-    counts: Record<string, number>;
-    complete: boolean;
-}
-/** A verified back-channel logout: every session for `sub` issued at or before `iat` is over. */
-interface LogoutToken {
-    sub: string;
-    iat: number;
-    jti: string;
-    exp: number;
-}
-
-/**
- * Server-side tokens for calling Broberg ID on the user's behalf (F095.1).
- *
- * The login already RECEIVES an access token and a refresh token; before 0.9.0
- * ssoRoutes dropped both, so an app could not call BID's app API (the account
- * page: read and change your own name and picture) as the user.
- *
- * ── WHY NOT IN THE COOKIE ────────────────────────────────────────────────
- * The session cookie is SIGNED, not encrypted, and the browser can read it. A
- * refresh token is the longest-lived, highest-value credential in the whole
- * flow: whoever holds it can mint access tokens until it is revoked. So the
- * tokens live server-side, keyed by a random `sid` that is the only thing the
- * cookie carries. A stolen cookie still needs the server to be useful.
- */
-interface TokenSet {
-    /** The BID subject the tokens belong to — lets «Log ud overalt» find them. */
-    sub: string;
-    accessToken: string;
-    refreshToken?: string;
-    /** Unix seconds. */
-    expiresAt: number;
-}
-/**
- * Where the tokens live. The APP provides it in production, backed by
- * something every instance shares (SQLite on one machine, a database or Redis
- * on several) — the same reason BackchannelStore has no in-memory default.
- */
-interface TokenStore {
-    get(sid: string): Promise<TokenSet | undefined>;
-    set(sid: string, tokens: TokenSet): Promise<void>;
-    delete(sid: string): Promise<void>;
-    /** Drop every token set for `sub` — what «Log ud overalt» calls. */
-    deleteSub(sub: string): Promise<void>;
-}
-
-/**
- * The app's OWN session cookie — signed, not encrypted.
- *
- * Signed is the right choice and the distinction matters: the contents are not
- * secret (a user may read their own id and name), but they must not be
- * FORGEABLE. Encryption would hide a subject id the user already knows while
- * doing nothing extra about forgery, which is the actual risk.
- *
- * What goes in is deliberately small: who you are and when this stops being
- * true. Claims that can change — a name, a role, a picture — belong in the
- * app's own store keyed by `sub`, because a cookie is a cache nobody can
- * invalidate, and a stale role in a cookie is a permission that outlives its
- * revocation.
- */
-interface SessionPayload {
-    /** The subject from Broberg ID. The one stable identifier. */
-    sub: string;
-    /** Unix seconds. Checked on every read. */
-    exp: number;
-    /**
-     * Unix seconds, when this session was minted. What «Log ud overalt» compares
-     * against (F084.151). Absent on sessions minted before 0.6.0 — those count as
-     * older than any logout.
-     */
-    iat?: number;
-    /**
-     * F095.1 — the key to this session's server-side tokens (ssoRoutes'
-     * `tokenStore`). Random, 128 bits. The tokens themselves are NEVER in the
-     * cookie: it is signed, not encrypted, and the browser can read it.
-     */
-    sid?: string;
-    /** Optional convenience copies; never authorisation data. */
-    email?: string;
-    name?: string;
-    /** A URL, never bytes. The picture lives wherever BID put it; this is a
-     *  reference, so a changed picture propagates without every app storing a
-     *  copy that then goes stale. */
-    picture?: string;
-    /**
-     * Whether BID has verified `email` (F084.152). Absent when BID did not say.
-     * Bind access to an address only when this is `true`.
-     */
-    email_verified?: boolean;
-}
+import { S as SsoClient, a as SsoConfig, T as TokenStore, b as SessionPayload } from './session-DsjOyCJb.js';
+import 'jose';
 
 /**
  * Where «Log ud overalt» is remembered (F084.151). The APP provides it, backed by