@broberg/sso 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,253 @@
+import { importJWK, JWTPayload } from 'jose';
+
+/**
+ * Configuration, read from the environment and nowhere else (F084.4 AC#5).
+ *
+ * An app mounts this package and sets env vars. It does not pass options in
+ * code, because the moment configuration lives in code, two deployments of the
+ * same app can disagree about who their identity provider is — and the symptom
+ * is a token rejection nobody can trace back to a config line.
+ */
+declare class SsoConfigError extends Error {
+    constructor(message: string);
+}
+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;
+}
+/** Seconds in a week — the fleet default from F084.7. */
+declare const DEFAULT_SESSION_MAX_AGE: number;
+declare function loadSsoConfig(env?: NodeJS.ProcessEnv): SsoConfig;
+
+/**
+ * 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.
+ */
+
+type SigningKey = Awaited<ReturnType<typeof importJWK>>;
+interface JwksCacheOptions {
+    /** Absolute URL of the key set, taken from BID's discovery document. */
+    jwksUri: string;
+    /**
+     * The floor between two refetches. Below it, an unknown kid is rejected
+     * without asking BID again.
+     */
+    minRefetchIntervalMs?: number;
+    /** Injectable for tests. */
+    fetchImpl?: typeof fetch;
+    /** Injectable for tests, so the cooldown can be exercised without waiting. */
+    now?: () => number;
+}
+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;
+}
+declare class JwksError extends Error {
+    constructor(message: string);
+}
+declare function createJwksCache(options: JwksCacheOptions): JwksCache;
+
+/**
+ * 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 {
+    issuer: string;
+    authorization_endpoint: string;
+    token_endpoint: string;
+    jwks_uri: string;
+    userinfo_endpoint?: string;
+    end_session_endpoint?: string;
+}
+declare class SsoError extends Error {
+    constructor(message: 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;
+    idToken: string;
+    accessToken?: string;
+    refreshToken?: string;
+}
+/**
+ * `prompt=none` asks BID to answer WITHOUT showing anything (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>;
+    /** Exposed for tests and for a health check; not needed in normal use. */
+    readonly jwks: JwksCache;
+}
+interface CreateSsoClientOptions {
+    fetchImpl?: typeof fetch;
+    /** Passed through to the key cache; see jwks.ts for why there is a floor. */
+    minRefetchIntervalMs?: number;
+}
+declare function createSsoClient(config: SsoConfig, options?: CreateSsoClientOptions): SsoClient;
+
+/**
+ * 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;
+    /** Optional convenience copies; never authorisation data. */
+    email?: string;
+    name?: string;
+}
+/**
+ * Sign an arbitrary string. The primitive underneath BOTH cookies this package
+ * sets — the session and the short-lived login transaction.
+ *
+ * They are separate functions on purpose. The first version of this file had
+ * the transaction ride inside the session envelope with `exp: 0`, and the
+ * expiry check (`exp * 1000 <= now()`) then rejected it every single time: the
+ * transaction cookie could never be read back, so every login would have failed
+ * with "state does not match" — a message pointing at the wrong thing entirely.
+ * Two different lifetimes wanted two different envelopes, not one envelope with
+ * a sentinel in it.
+ */
+declare function signValue(value: string, secret: string): Promise<string>;
+/** Verify the SIGNATURE only, returning the original string. No expiry notion. */
+declare function verifyValue(token: string | undefined | null, secret: string): Promise<string | null>;
+declare function signSession(payload: SessionPayload, secret: string): Promise<string>;
+/**
+ * Returns null for ANY reason the cookie cannot be trusted — tampered,
+ * truncated, wrong secret, expired, or simply not one of ours.
+ *
+ * Deliberately one return value rather than distinguishing them to the caller:
+ * an app that can tell "bad signature" from "expired" will eventually branch on
+ * it, and there is no branch where a forged cookie should do anything other
+ * than what an absent one does.
+ */
+declare function verifySession(token: string | undefined | null, secret: string, now?: () => number): Promise<SessionPayload | null>;
+/** Serialise a Set-Cookie value. `secure` is off only for http://localhost. */
+declare function cookieHeader(name: string, value: string, opts: {
+    maxAge: number;
+    secure: boolean;
+    sameSite?: "Lax" | "Strict";
+    path?: string;
+}): string;
+declare function readCookie(header: string | null | undefined, name: string): string | undefined;
+
+export { type BeginLoginOptions, type CreateSsoClientOptions, DEFAULT_SESSION_MAX_AGE, type Discovery, type JwksCache, type JwksCacheOptions, JwksError, type LoginResult, type LoginStart, type SessionPayload, type SsoClaims, type SsoClient, type SsoConfig, SsoConfigError, SsoError, cookieHeader, createJwksCache, createSsoClient, loadSsoConfig, readCookie, signSession, signValue, verifySession, verifyValue };

package/dist/index.d.ts

@@ -0,0 +1,253 @@
+import { importJWK, JWTPayload } from 'jose';
+
+/**
+ * Configuration, read from the environment and nowhere else (F084.4 AC#5).
+ *
+ * An app mounts this package and sets env vars. It does not pass options in
+ * code, because the moment configuration lives in code, two deployments of the
+ * same app can disagree about who their identity provider is — and the symptom
+ * is a token rejection nobody can trace back to a config line.
+ */
+declare class SsoConfigError extends Error {
+    constructor(message: string);
+}
+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;
+}
+/** Seconds in a week — the fleet default from F084.7. */
+declare const DEFAULT_SESSION_MAX_AGE: number;
+declare function loadSsoConfig(env?: NodeJS.ProcessEnv): SsoConfig;
+
+/**
+ * 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.
+ */
+
+type SigningKey = Awaited<ReturnType<typeof importJWK>>;
+interface JwksCacheOptions {
+    /** Absolute URL of the key set, taken from BID's discovery document. */
+    jwksUri: string;
+    /**
+     * The floor between two refetches. Below it, an unknown kid is rejected
+     * without asking BID again.
+     */
+    minRefetchIntervalMs?: number;
+    /** Injectable for tests. */
+    fetchImpl?: typeof fetch;
+    /** Injectable for tests, so the cooldown can be exercised without waiting. */
+    now?: () => number;
+}
+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;
+}
+declare class JwksError extends Error {
+    constructor(message: string);
+}
+declare function createJwksCache(options: JwksCacheOptions): JwksCache;
+
+/**
+ * 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 {
+    issuer: string;
+    authorization_endpoint: string;
+    token_endpoint: string;
+    jwks_uri: string;
+    userinfo_endpoint?: string;
+    end_session_endpoint?: string;
+}
+declare class SsoError extends Error {
+    constructor(message: 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;
+    idToken: string;
+    accessToken?: string;
+    refreshToken?: string;
+}
+/**
+ * `prompt=none` asks BID to answer WITHOUT showing anything (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>;
+    /** Exposed for tests and for a health check; not needed in normal use. */
+    readonly jwks: JwksCache;
+}
+interface CreateSsoClientOptions {
+    fetchImpl?: typeof fetch;
+    /** Passed through to the key cache; see jwks.ts for why there is a floor. */
+    minRefetchIntervalMs?: number;
+}
+declare function createSsoClient(config: SsoConfig, options?: CreateSsoClientOptions): SsoClient;
+
+/**
+ * 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;
+    /** Optional convenience copies; never authorisation data. */
+    email?: string;
+    name?: string;
+}
+/**
+ * Sign an arbitrary string. The primitive underneath BOTH cookies this package
+ * sets — the session and the short-lived login transaction.
+ *
+ * They are separate functions on purpose. The first version of this file had
+ * the transaction ride inside the session envelope with `exp: 0`, and the
+ * expiry check (`exp * 1000 <= now()`) then rejected it every single time: the
+ * transaction cookie could never be read back, so every login would have failed
+ * with "state does not match" — a message pointing at the wrong thing entirely.
+ * Two different lifetimes wanted two different envelopes, not one envelope with
+ * a sentinel in it.
+ */
+declare function signValue(value: string, secret: string): Promise<string>;
+/** Verify the SIGNATURE only, returning the original string. No expiry notion. */
+declare function verifyValue(token: string | undefined | null, secret: string): Promise<string | null>;
+declare function signSession(payload: SessionPayload, secret: string): Promise<string>;
+/**
+ * Returns null for ANY reason the cookie cannot be trusted — tampered,
+ * truncated, wrong secret, expired, or simply not one of ours.
+ *
+ * Deliberately one return value rather than distinguishing them to the caller:
+ * an app that can tell "bad signature" from "expired" will eventually branch on
+ * it, and there is no branch where a forged cookie should do anything other
+ * than what an absent one does.
+ */
+declare function verifySession(token: string | undefined | null, secret: string, now?: () => number): Promise<SessionPayload | null>;
+/** Serialise a Set-Cookie value. `secure` is off only for http://localhost. */
+declare function cookieHeader(name: string, value: string, opts: {
+    maxAge: number;
+    secure: boolean;
+    sameSite?: "Lax" | "Strict";
+    path?: string;
+}): string;
+declare function readCookie(header: string | null | undefined, name: string): string | undefined;
+
+export { type BeginLoginOptions, type CreateSsoClientOptions, DEFAULT_SESSION_MAX_AGE, type Discovery, type JwksCache, type JwksCacheOptions, JwksError, type LoginResult, type LoginStart, type SessionPayload, type SsoClaims, type SsoClient, type SsoConfig, SsoConfigError, SsoError, cookieHeader, createJwksCache, createSsoClient, loadSsoConfig, readCookie, signSession, signValue, verifySession, verifyValue };