@broberg/sso 0.12.0 → 0.13.0

package/dist/index.d.cts

@@ -422,6 +422,53 @@ interface CreateSsoClientOptions {
 }
 declare function createSsoClient(config: SsoConfig, options?: CreateSsoClientOptions): SsoClient;
 
+type PrincipalType = "human" | "service" | "agent";
+/** What a verified ticket tells the receiver — a small, typed principal, never the raw payload. */
+interface TicketPrincipal {
+    /** Who is calling: the ticket's `sub` (a client id such as `svc-trail`). */
+    principal: string;
+    type: PrincipalType;
+    /** The client the ticket was issued to (`client_id`, falling back to `sub`). */
+    clientId: string;
+    /** The organisation, when BID stated one. */
+    org: string | null;
+    /** On delegation: who the caller is acting for (RFC 8693 `act.sub`). */
+    act: {
+        sub: string;
+    } | null;
+    scopes: string[];
+    /** Seconds since the epoch. */
+    exp: number;
+    jti: string;
+}
+interface TicketVerifierOptions {
+    /** BID's issuer, exactly as it signs `iss` — e.g. `https://id.broberg.ai`. */
+    issuer: string;
+    /** THIS receiver's audience — its own URL, e.g. `https://discovery.broberg.ai`. */
+    audience: string;
+    /** The key set URL. Omitted: read once from the issuer's discovery document. */
+    jwksUri?: string;
+    /**
+     * The longest lifetime (exp − iat) a ticket may claim. BID issues 5 min
+     * (service) and 15 min (agent); anything longer was not minted by the policy
+     * we were told about, so it is refused rather than trusted for longer.
+     */
+    maxLifetimeSec?: number;
+    /** Seconds of clock skew to allow on exp/iat. Default 30. */
+    clockToleranceSec?: number;
+    /** Fetch the key set at construction, so the first caller does not wait. */
+    warmUp?: boolean;
+    fetchImpl?: typeof fetch;
+    minRefetchIntervalMs?: number;
+}
+interface TicketVerifier {
+    /** Verify a ticket; with `scope`, also require that scope to be granted. */
+    verify(token: string, options?: {
+        scope?: string | string[];
+    }): Promise<TicketPrincipal>;
+}
+declare function createTicketVerifier(options: TicketVerifierOptions): TicketVerifier;
+
 /**
  * The app's OWN session cookie — signed, not encrypted.
  *
@@ -577,4 +624,4 @@ declare function memoryTokenStore(options?: {
     readonly size: number;
 };
 
-export { AVATAR_TYPES, type AddressOwnership, type BeginLoginOptions, type BidProfile, type CreateSsoClientOptions, DEFAULT_SESSION_MAX_AGE, type Discovery, type InvitationOutcome, type InvitationResult, type InviteUsersInput, type JwksCache, type JwksCacheOptions, JwksError, JwksUnavailableError, JwksUnknownKeyError, type LoginResult, type LoginStart, type LogoutToken, MAX_AVATAR_BYTES, MAX_INVITATIONS, type MigrationState, type MigrationStatus, type SessionPayload, SsoAppApiError, SsoAvatarRejectedError, type SsoClaims, type SsoClient, type SsoConfig, SsoConfigError, SsoError, SsoInsufficientScopeError, SsoReauthError, type TokenSet, type TokenStore, cookieHeader, createJwksCache, createSsoClient, loadSsoConfig, memoryTokenStore, readCookie, signSession, signValue, verifySession, verifyValue };
+export { AVATAR_TYPES, type AddressOwnership, type BeginLoginOptions, type BidProfile, type CreateSsoClientOptions, DEFAULT_SESSION_MAX_AGE, type Discovery, type InvitationOutcome, type InvitationResult, type InviteUsersInput, type JwksCache, type JwksCacheOptions, JwksError, JwksUnavailableError, JwksUnknownKeyError, type LoginResult, type LoginStart, type LogoutToken, MAX_AVATAR_BYTES, MAX_INVITATIONS, type MigrationState, type MigrationStatus, type PrincipalType, type SessionPayload, SsoAppApiError, SsoAvatarRejectedError, type SsoClaims, type SsoClient, type SsoConfig, SsoConfigError, SsoError, SsoInsufficientScopeError, SsoReauthError, type TicketPrincipal, type TicketVerifier, type TicketVerifierOptions, type TokenSet, type TokenStore, cookieHeader, createJwksCache, createSsoClient, createTicketVerifier, loadSsoConfig, memoryTokenStore, readCookie, signSession, signValue, verifySession, verifyValue };

package/dist/index.d.ts

@@ -422,6 +422,53 @@ interface CreateSsoClientOptions {
 }
 declare function createSsoClient(config: SsoConfig, options?: CreateSsoClientOptions): SsoClient;
 
+type PrincipalType = "human" | "service" | "agent";
+/** What a verified ticket tells the receiver — a small, typed principal, never the raw payload. */
+interface TicketPrincipal {
+    /** Who is calling: the ticket's `sub` (a client id such as `svc-trail`). */
+    principal: string;
+    type: PrincipalType;
+    /** The client the ticket was issued to (`client_id`, falling back to `sub`). */
+    clientId: string;
+    /** The organisation, when BID stated one. */
+    org: string | null;
+    /** On delegation: who the caller is acting for (RFC 8693 `act.sub`). */
+    act: {
+        sub: string;
+    } | null;
+    scopes: string[];
+    /** Seconds since the epoch. */
+    exp: number;
+    jti: string;
+}
+interface TicketVerifierOptions {
+    /** BID's issuer, exactly as it signs `iss` — e.g. `https://id.broberg.ai`. */
+    issuer: string;
+    /** THIS receiver's audience — its own URL, e.g. `https://discovery.broberg.ai`. */
+    audience: string;
+    /** The key set URL. Omitted: read once from the issuer's discovery document. */
+    jwksUri?: string;
+    /**
+     * The longest lifetime (exp − iat) a ticket may claim. BID issues 5 min
+     * (service) and 15 min (agent); anything longer was not minted by the policy
+     * we were told about, so it is refused rather than trusted for longer.
+     */
+    maxLifetimeSec?: number;
+    /** Seconds of clock skew to allow on exp/iat. Default 30. */
+    clockToleranceSec?: number;
+    /** Fetch the key set at construction, so the first caller does not wait. */
+    warmUp?: boolean;
+    fetchImpl?: typeof fetch;
+    minRefetchIntervalMs?: number;
+}
+interface TicketVerifier {
+    /** Verify a ticket; with `scope`, also require that scope to be granted. */
+    verify(token: string, options?: {
+        scope?: string | string[];
+    }): Promise<TicketPrincipal>;
+}
+declare function createTicketVerifier(options: TicketVerifierOptions): TicketVerifier;
+
 /**
  * The app's OWN session cookie — signed, not encrypted.
  *
@@ -577,4 +624,4 @@ declare function memoryTokenStore(options?: {
     readonly size: number;
 };
 
-export { AVATAR_TYPES, type AddressOwnership, type BeginLoginOptions, type BidProfile, type CreateSsoClientOptions, DEFAULT_SESSION_MAX_AGE, type Discovery, type InvitationOutcome, type InvitationResult, type InviteUsersInput, type JwksCache, type JwksCacheOptions, JwksError, JwksUnavailableError, JwksUnknownKeyError, type LoginResult, type LoginStart, type LogoutToken, MAX_AVATAR_BYTES, MAX_INVITATIONS, type MigrationState, type MigrationStatus, type SessionPayload, SsoAppApiError, SsoAvatarRejectedError, type SsoClaims, type SsoClient, type SsoConfig, SsoConfigError, SsoError, SsoInsufficientScopeError, SsoReauthError, type TokenSet, type TokenStore, cookieHeader, createJwksCache, createSsoClient, loadSsoConfig, memoryTokenStore, readCookie, signSession, signValue, verifySession, verifyValue };
+export { AVATAR_TYPES, type AddressOwnership, type BeginLoginOptions, type BidProfile, type CreateSsoClientOptions, DEFAULT_SESSION_MAX_AGE, type Discovery, type InvitationOutcome, type InvitationResult, type InviteUsersInput, type JwksCache, type JwksCacheOptions, JwksError, JwksUnavailableError, JwksUnknownKeyError, type LoginResult, type LoginStart, type LogoutToken, MAX_AVATAR_BYTES, MAX_INVITATIONS, type MigrationState, type MigrationStatus, type PrincipalType, type SessionPayload, SsoAppApiError, SsoAvatarRejectedError, type SsoClaims, type SsoClient, type SsoConfig, SsoConfigError, SsoError, SsoInsufficientScopeError, SsoReauthError, type TicketPrincipal, type TicketVerifier, type TicketVerifierOptions, type TokenSet, type TokenStore, cookieHeader, createJwksCache, createSsoClient, createTicketVerifier, loadSsoConfig, memoryTokenStore, readCookie, signSession, signValue, verifySession, verifyValue };

package/dist/index.js

@@ -664,6 +664,103 @@ function createSsoClient(config, options = {}) {
     }
   };
 }
+var PRINCIPAL_TYPES = ["human", "service", "agent"];
+function createTicketVerifier(options) {
+  const {
+    issuer,
+    audience,
+    maxLifetimeSec = 15 * 60,
+    clockToleranceSec = 30,
+    fetchImpl = fetch
+  } = options;
+  if (!issuer) throw new SsoError("createTicketVerifier needs an issuer");
+  if (!audience) throw new SsoError("createTicketVerifier needs this receiver's audience");
+  let cachePromise = null;
+  const cacheFor = (jwksUri) => createJwksCache({
+    jwksUri,
+    fetchImpl,
+    ...options.warmUp ? { warmUp: true } : {},
+    ...options.minRefetchIntervalMs !== void 0 ? { minRefetchIntervalMs: options.minRefetchIntervalMs } : {}
+  });
+  async function keys() {
+    cachePromise ??= (async () => {
+      if (options.jwksUri) return cacheFor(options.jwksUri);
+      const url = `${issuer}/.well-known/openid-configuration`;
+      let doc;
+      try {
+        const res = await fetchImpl(url);
+        if (!res.ok) throw new Error(`answered ${res.status}`);
+        doc = await res.json();
+      } catch (cause) {
+        throw new JwksUnavailableError(`${url}: ${cause instanceof Error ? cause.message : String(cause)}`);
+      }
+      if (doc.issuer !== issuer) {
+        throw new SsoError(`issuer is ${issuer} but ${url} says ${doc.issuer} \u2014 they must match exactly`);
+      }
+      if (!doc.jwks_uri) throw new SsoError(`${url} names no jwks_uri`);
+      return cacheFor(doc.jwks_uri);
+    })().catch((err) => {
+      cachePromise = null;
+      throw err;
+    });
+    return cachePromise;
+  }
+  if (options.warmUp) void keys().catch(() => {
+  });
+  return {
+    async verify(token, opts = {}) {
+      let header;
+      try {
+        header = decodeProtectedHeader(token);
+      } catch {
+        throw new SsoError("ticket is not a JWS");
+      }
+      if (!header.kid) throw new SsoError("ticket has no kid \u2014 cannot pick a signing key");
+      if (header.typ === "logout+jwt") throw new SsoError("a logout token is not a ticket");
+      const cache = await keys();
+      let payload;
+      try {
+        ({ payload } = await jwtVerify(token, async () => cache.getKey(header.kid, header.alg ?? "EdDSA"), {
+          issuer,
+          audience,
+          algorithms: ALLOWED_ALGS,
+          clockTolerance: clockToleranceSec,
+          requiredClaims: ["exp", "iat", "jti", "sub"]
+        }));
+      } catch (e) {
+        if (e instanceof JwksUnavailableError) throw e;
+        throw new SsoError(`ticket rejected: ${e instanceof Error ? e.message : String(e)}`);
+      }
+      if ("events" in payload) throw new SsoError("a logout token is not a ticket");
+      if ("nonce" in payload) throw new SsoError("an ID token is not a ticket");
+      const type = payload.principal_type;
+      if (typeof type !== "string" || !PRINCIPAL_TYPES.includes(type)) {
+        throw new SsoError(`ticket has no valid principal_type (got ${JSON.stringify(type)})`);
+      }
+      const lifetime = payload.exp - payload.iat;
+      if (lifetime > maxLifetimeSec) {
+        throw new SsoError(`ticket claims a ${lifetime}s lifetime; at most ${maxLifetimeSec}s is accepted`);
+      }
+      if (typeof payload.sub !== "string" || payload.sub === "") throw new SsoError("ticket has no sub");
+      const scopes = typeof payload.scope === "string" ? payload.scope.split(" ").filter(Boolean) : [];
+      const required2 = opts.scope === void 0 ? [] : Array.isArray(opts.scope) ? opts.scope : [opts.scope];
+      const missing = required2.filter((s) => !scopes.includes(s));
+      if (missing.length) throw new SsoError(`ticket lacks scope ${missing.join(", ")}`);
+      const actRaw = payload.act;
+      const act = actRaw && typeof actRaw.sub === "string" && actRaw.sub ? { sub: actRaw.sub } : null;
+      return {
+        principal: payload.sub,
+        type,
+        clientId: typeof payload.client_id === "string" && payload.client_id ? payload.client_id : payload.sub,
+        org: typeof payload.org === "string" && payload.org ? payload.org : null,
+        act,
+        scopes,
+        exp: payload.exp,
+        jti: String(payload.jti)
+      };
+    }
+  };
+}
 
 // src/session.ts
 var enc = new TextEncoder();
@@ -784,6 +881,6 @@ function memoryTokenStore(options = {}) {
   };
 }
 
-export { AVATAR_TYPES, DEFAULT_SESSION_MAX_AGE, JwksError, JwksUnavailableError, JwksUnknownKeyError, MAX_AVATAR_BYTES, MAX_INVITATIONS, SsoAppApiError, SsoAvatarRejectedError, SsoConfigError, SsoError, SsoInsufficientScopeError, SsoReauthError, cookieHeader, createJwksCache, createSsoClient, loadSsoConfig, memoryTokenStore, readCookie, signSession, signValue, verifySession, verifyValue };
+export { AVATAR_TYPES, DEFAULT_SESSION_MAX_AGE, JwksError, JwksUnavailableError, JwksUnknownKeyError, MAX_AVATAR_BYTES, MAX_INVITATIONS, SsoAppApiError, SsoAvatarRejectedError, SsoConfigError, SsoError, SsoInsufficientScopeError, SsoReauthError, cookieHeader, createJwksCache, createSsoClient, createTicketVerifier, loadSsoConfig, memoryTokenStore, readCookie, signSession, signValue, verifySession, verifyValue };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map