@broberg/sso 0.13.0 → 0.14.1

package/dist/index.d.cts

@@ -422,6 +422,52 @@ interface CreateSsoClientOptions {
 }
 declare function createSsoClient(config: SsoConfig, options?: CreateSsoClientOptions): SsoClient;
 
+declare const DEFAULT_ISSUER = "https://id.broberg.ai";
+/** No platform identity to exchange: not on Fly, not in a GitHub Actions job with id-token: write. */
+declare class NoWorkloadIdentityError extends Error {
+    constructor(message: string);
+}
+/**
+ * BID refused the exchange. `code` is BID's own error name (the part of
+ * error_description before the colon, e.g. `no_rule_for_audience`), `status` the
+ * HTTP status. A 4xx is PERMANENT for this request — fix the rule, do not retry.
+ */
+declare class TicketExchangeError extends Error {
+    readonly code: string;
+    readonly status: number;
+    constructor(message: string, code: string, status: number);
+}
+/** BID or the platform could not be reached, or answered 5xx. TRANSIENT — retry later. */
+declare class TicketUnavailableError extends Error {
+    constructor(message: string);
+}
+interface TicketClientOptions {
+    issuer?: string;
+    /** Renew this many seconds before exp. Default 30. */
+    renewBeforeSec?: number;
+    /** Injectable for tests. */
+    env?: Record<string, string | undefined>;
+    fetchImpl?: typeof fetch;
+    now?: () => number;
+    /** Ask Fly's machine API for an OIDC token. Default: POST over the /.fly/api unix socket. */
+    flyOidc?: (aud: string) => Promise<string>;
+    /** Whether the Fly socket is present. Default: checks /.fly/api. */
+    onFly?: () => boolean;
+}
+interface TicketClient {
+    /** A ticket for `audience` (BID's short name, e.g. "discovery"), from cache while it is fresh. */
+    get(opts: {
+        audience: string;
+        scope?: string;
+    }): Promise<string>;
+}
+declare function createTicketClient(options?: TicketClientOptions): TicketClient;
+/** A ticket from the process-wide client (one cache per process). */
+declare function fetchTicket(opts: {
+    audience: string;
+    scope?: string;
+}): Promise<string>;
+
 type PrincipalType = "human" | "service" | "agent";
 /** What a verified ticket tells the receiver — a small, typed principal, never the raw payload. */
 interface TicketPrincipal {
@@ -624,4 +670,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 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 };
+export { AVATAR_TYPES, type AddressOwnership, type BeginLoginOptions, type BidProfile, type CreateSsoClientOptions, DEFAULT_ISSUER, 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, NoWorkloadIdentityError, type PrincipalType, type SessionPayload, SsoAppApiError, SsoAvatarRejectedError, type SsoClaims, type SsoClient, type SsoConfig, SsoConfigError, SsoError, SsoInsufficientScopeError, SsoReauthError, type TicketClient, type TicketClientOptions, TicketExchangeError, type TicketPrincipal, TicketUnavailableError, type TicketVerifier, type TicketVerifierOptions, type TokenSet, type TokenStore, cookieHeader, createJwksCache, createSsoClient, createTicketClient, createTicketVerifier, fetchTicket, loadSsoConfig, memoryTokenStore, readCookie, signSession, signValue, verifySession, verifyValue };

package/dist/index.d.ts

@@ -422,6 +422,52 @@ interface CreateSsoClientOptions {
 }
 declare function createSsoClient(config: SsoConfig, options?: CreateSsoClientOptions): SsoClient;
 
+declare const DEFAULT_ISSUER = "https://id.broberg.ai";
+/** No platform identity to exchange: not on Fly, not in a GitHub Actions job with id-token: write. */
+declare class NoWorkloadIdentityError extends Error {
+    constructor(message: string);
+}
+/**
+ * BID refused the exchange. `code` is BID's own error name (the part of
+ * error_description before the colon, e.g. `no_rule_for_audience`), `status` the
+ * HTTP status. A 4xx is PERMANENT for this request — fix the rule, do not retry.
+ */
+declare class TicketExchangeError extends Error {
+    readonly code: string;
+    readonly status: number;
+    constructor(message: string, code: string, status: number);
+}
+/** BID or the platform could not be reached, or answered 5xx. TRANSIENT — retry later. */
+declare class TicketUnavailableError extends Error {
+    constructor(message: string);
+}
+interface TicketClientOptions {
+    issuer?: string;
+    /** Renew this many seconds before exp. Default 30. */
+    renewBeforeSec?: number;
+    /** Injectable for tests. */
+    env?: Record<string, string | undefined>;
+    fetchImpl?: typeof fetch;
+    now?: () => number;
+    /** Ask Fly's machine API for an OIDC token. Default: POST over the /.fly/api unix socket. */
+    flyOidc?: (aud: string) => Promise<string>;
+    /** Whether the Fly socket is present. Default: checks /.fly/api. */
+    onFly?: () => boolean;
+}
+interface TicketClient {
+    /** A ticket for `audience` (BID's short name, e.g. "discovery"), from cache while it is fresh. */
+    get(opts: {
+        audience: string;
+        scope?: string;
+    }): Promise<string>;
+}
+declare function createTicketClient(options?: TicketClientOptions): TicketClient;
+/** A ticket from the process-wide client (one cache per process). */
+declare function fetchTicket(opts: {
+    audience: string;
+    scope?: string;
+}): Promise<string>;
+
 type PrincipalType = "human" | "service" | "agent";
 /** What a verified ticket tells the receiver — a small, typed principal, never the raw payload. */
 interface TicketPrincipal {
@@ -624,4 +670,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 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 };
+export { AVATAR_TYPES, type AddressOwnership, type BeginLoginOptions, type BidProfile, type CreateSsoClientOptions, DEFAULT_ISSUER, 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, NoWorkloadIdentityError, type PrincipalType, type SessionPayload, SsoAppApiError, SsoAvatarRejectedError, type SsoClaims, type SsoClient, type SsoConfig, SsoConfigError, SsoError, SsoInsufficientScopeError, SsoReauthError, type TicketClient, type TicketClientOptions, TicketExchangeError, type TicketPrincipal, TicketUnavailableError, type TicketVerifier, type TicketVerifierOptions, type TokenSet, type TokenStore, cookieHeader, createJwksCache, createSsoClient, createTicketClient, createTicketVerifier, fetchTicket, loadSsoConfig, memoryTokenStore, readCookie, signSession, signValue, verifySession, verifyValue };

package/dist/index.js

@@ -1,4 +1,6 @@
 import { importJWK, decodeProtectedHeader, jwtVerify } from 'jose';
+import { existsSync } from 'fs';
+import { request } from 'http';
 
 // src/config.ts
 var SsoConfigError = class extends Error {
@@ -664,6 +666,142 @@ function createSsoClient(config, options = {}) {
     }
   };
 }
+var DEFAULT_ISSUER = "https://id.broberg.ai";
+var FLY_SOCKET = "/.fly/api";
+var NoWorkloadIdentityError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "NoWorkloadIdentityError";
+  }
+};
+var TicketExchangeError = class extends Error {
+  constructor(message, code, status) {
+    super(message);
+    this.code = code;
+    this.status = status;
+    this.name = "TicketExchangeError";
+  }
+  code;
+  status;
+};
+var TicketUnavailableError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "TicketUnavailableError";
+  }
+};
+function flyOidcOverSocket(aud) {
+  return new Promise((resolve, reject) => {
+    const body = JSON.stringify({ aud });
+    const req = request(
+      { socketPath: FLY_SOCKET, path: "/v1/tokens/oidc", method: "POST", headers: { "content-type": "application/json", "content-length": Buffer.byteLength(body) } },
+      (res) => {
+        let data = "";
+        res.setEncoding("utf8");
+        res.on("data", (c) => data += c);
+        res.on("end", () => {
+          if ((res.statusCode ?? 0) >= 200 && (res.statusCode ?? 0) < 300) resolve(data.trim());
+          else reject(new TicketUnavailableError(`Fly OIDC answered ${res.statusCode}`));
+        });
+      }
+    );
+    req.on("error", (e) => reject(new TicketUnavailableError(`Fly OIDC socket: ${e.message}`)));
+    req.end(body);
+  });
+}
+function jwtExp(token) {
+  try {
+    const payload = JSON.parse(Buffer.from(token.split(".")[1] ?? "", "base64url").toString("utf8"));
+    return typeof payload.exp === "number" ? payload.exp : null;
+  } catch {
+    return null;
+  }
+}
+function createTicketClient(options = {}) {
+  const issuer = (options.issuer ?? DEFAULT_ISSUER).replace(/\/+$/, "");
+  const renewBeforeSec = options.renewBeforeSec ?? 30;
+  const env = options.env ?? process.env;
+  const fetchImpl = options.fetchImpl ?? fetch;
+  const now = options.now ?? (() => Date.now());
+  const flyOidc = options.flyOidc ?? flyOidcOverSocket;
+  const onFly = options.onFly ?? (() => !!env.FLY_APP_NAME && existsSync(FLY_SOCKET));
+  const cache = /* @__PURE__ */ new Map();
+  const inFlight = /* @__PURE__ */ new Map();
+  async function platformToken() {
+    if (onFly()) return flyOidc(issuer);
+    const url = env.ACTIONS_ID_TOKEN_REQUEST_URL;
+    const bearer = env.ACTIONS_ID_TOKEN_REQUEST_TOKEN;
+    if (url && bearer) {
+      let res;
+      try {
+        res = await fetchImpl(`${url}&audience=${encodeURIComponent(issuer)}`, { headers: { authorization: `Bearer ${bearer}` } });
+      } catch (e) {
+        throw new TicketUnavailableError(`GitHub OIDC endpoint unreachable: ${e instanceof Error ? e.message : String(e)}`);
+      }
+      if (!res.ok) throw new TicketUnavailableError(`GitHub OIDC endpoint answered ${res.status}`);
+      const { value } = await res.json();
+      if (!value) throw new TicketUnavailableError("GitHub OIDC endpoint returned no token");
+      return value;
+    }
+    throw new NoWorkloadIdentityError(
+      "No workload identity to exchange for a ticket: not on a Fly machine (FLY_APP_NAME + /.fly/api) and not in a GitHub Actions job (ACTIONS_ID_TOKEN_REQUEST_URL/_TOKEN \u2014 add `permissions: id-token: write`). A Mac session keeps using its session key."
+    );
+  }
+  async function exchange(audience, scope) {
+    const subject = await platformToken();
+    const form = new URLSearchParams({
+      grant_type: "urn:ietf:params:oauth:grant-type:token-exchange",
+      subject_token: subject,
+      subject_token_type: "urn:ietf:params:oauth:token-type:jwt",
+      audience
+    });
+    if (scope) form.set("scope", scope);
+    let res;
+    try {
+      res = await fetchImpl(`${issuer}/oauth2/token`, {
+        method: "POST",
+        headers: { "content-type": "application/x-www-form-urlencoded" },
+        body: form
+      });
+    } catch (e) {
+      throw new TicketUnavailableError(`${issuer} unreachable: ${e instanceof Error ? e.message : String(e)}`);
+    }
+    let body = {};
+    try {
+      body = await res.json();
+    } catch {
+    }
+    if (res.status >= 500) throw new TicketUnavailableError(`${issuer} answered ${res.status}`);
+    if (!res.ok || !body.access_token) {
+      const desc = body.error_description ?? "";
+      const code = desc.includes(":") ? desc.slice(0, desc.indexOf(":")).trim() : body.error ?? "exchange_refused";
+      throw new TicketExchangeError(`Broberg ID refused the ticket for ${audience}: ${desc || body.error || res.status}`, code, res.status);
+    }
+    const nowSec = Math.floor(now() / 1e3);
+    const exp = jwtExp(body.access_token) ?? nowSec + (body.expires_in ?? 300);
+    return { token: body.access_token, exp };
+  }
+  return {
+    async get({ audience, scope }) {
+      const key = `${audience} ${scope ?? ""}`;
+      const hit = cache.get(key);
+      if (hit && hit.exp - renewBeforeSec > now() / 1e3) return hit.token;
+      const pending = inFlight.get(key);
+      if (pending) return pending;
+      const p = exchange(audience, scope).then((t) => {
+        cache.set(key, t);
+        return t.token;
+      }).finally(() => inFlight.delete(key));
+      inFlight.set(key, p);
+      return p;
+    }
+  };
+}
+var shared = null;
+function fetchTicket(opts) {
+  shared ??= createTicketClient();
+  return shared.get(opts);
+}
 var PRINCIPAL_TYPES = ["human", "service", "agent"];
 function createTicketVerifier(options) {
   const {
@@ -881,6 +1019,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, createTicketVerifier, loadSsoConfig, memoryTokenStore, readCookie, signSession, signValue, verifySession, verifyValue };
+export { AVATAR_TYPES, DEFAULT_ISSUER, DEFAULT_SESSION_MAX_AGE, JwksError, JwksUnavailableError, JwksUnknownKeyError, MAX_AVATAR_BYTES, MAX_INVITATIONS, NoWorkloadIdentityError, SsoAppApiError, SsoAvatarRejectedError, SsoConfigError, SsoError, SsoInsufficientScopeError, SsoReauthError, TicketExchangeError, TicketUnavailableError, cookieHeader, createJwksCache, createSsoClient, createTicketClient, createTicketVerifier, fetchTicket, loadSsoConfig, memoryTokenStore, readCookie, signSession, signValue, verifySession, verifyValue };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map