@broberg/sso 0.13.0 → 0.14.1

package/README.md

@@ -552,3 +552,21 @@ try {
 - **Never accepted as a ticket:** an ID token or a logout token, even though BID signed both.
 - **BID briefly down:** a key already in the cache still verifies, with no network call. An unknown key while BID is down throws `JwksUnavailableError` — answer 503, do not reject the caller.
 - Not a login client: a service that only receives tickets needs no `client_id`, no redirect and no session.
+
+## Getting a ticket — `fetchTicket` (since 0.14.1 — 0.14.0 was tagged but never reached npm)
+
+The sending half: a workload on **Fly** or in **GitHub Actions** gets a Broberg ID ticket with no key at all. It proves who it is with the identity its platform already gives it, and BID exchanges that (RFC 8693). Nothing secret is stored anywhere.
+
+```ts
+import { fetchTicket, NoWorkloadIdentityError, TicketExchangeError, TicketUnavailableError } from "@broberg/sso";
+
+const ticket = await fetchTicket({ audience: "discovery", scope: "discovery:read" });
+await fetch("https://discovery.broberg.ai/api/fleet", { headers: { authorization: `Bearer ${ticket}` } });
+```
+
+- **Fly:** asks the machine API (`unix:/.fly/api`, `POST /v1/tokens/oidc`, `aud` = the issuer). The ticket's subject is `svc:<fly app name>` — BID derives it from the app name, so the rule in BID must name the app exactly.
+- **GitHub Actions:** uses `ACTIONS_ID_TOKEN_REQUEST_URL` / `_TOKEN`; the workflow needs `permissions: id-token: write`. Subject `svc:gh:<owner>/<repo>`, and BID's rule names ONE workflow file (a new file cannot get a ticket).
+- **Anywhere else** (a Mac session, a laptop): `NoWorkloadIdentityError` — keep using the session key there.
+- **Cached** per audience + scope until 30 s before exp (BID issues 5 min), and concurrent calls share one exchange. `createTicketClient({...})` gives you your own cache and injectable platform/fetch for tests.
+- **Errors:** `TicketExchangeError` (BID refused — `code` is BID's name for it, `status` the HTTP status; permanent, fix the rule) · `TicketUnavailableError` (BID or the platform unreachable / 5xx; transient) · `NoWorkloadIdentityError`. BID's codes include `no_rule_for_audience`, `scope_not_allowed`, `service_not_registered`, `audience_unknown`, `workflow_not_allowed`, `fly_org_untrusted`, `fly_audience_mismatch`, `github_owner_untrusted`, `client_mismatch`, `issuer_unknown`.
+- The ticket is never logged or put in an error message.

package/dist/index.cjs

@@ -1,6 +1,8 @@
 'use strict';
 
 var jose = require('jose');
+var fs = require('fs');
+var http = require('http');
 
 // src/config.ts
 var SsoConfigError = class extends Error {
@@ -666,6 +668,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 = http.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 && fs.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 {
@@ -884,22 +1022,28 @@ function memoryTokenStore(options = {}) {
 }
 
 exports.AVATAR_TYPES = AVATAR_TYPES;
+exports.DEFAULT_ISSUER = DEFAULT_ISSUER;
 exports.DEFAULT_SESSION_MAX_AGE = DEFAULT_SESSION_MAX_AGE;
 exports.JwksError = JwksError;
 exports.JwksUnavailableError = JwksUnavailableError;
 exports.JwksUnknownKeyError = JwksUnknownKeyError;
 exports.MAX_AVATAR_BYTES = MAX_AVATAR_BYTES;
 exports.MAX_INVITATIONS = MAX_INVITATIONS;
+exports.NoWorkloadIdentityError = NoWorkloadIdentityError;
 exports.SsoAppApiError = SsoAppApiError;
 exports.SsoAvatarRejectedError = SsoAvatarRejectedError;
 exports.SsoConfigError = SsoConfigError;
 exports.SsoError = SsoError;
 exports.SsoInsufficientScopeError = SsoInsufficientScopeError;
 exports.SsoReauthError = SsoReauthError;
+exports.TicketExchangeError = TicketExchangeError;
+exports.TicketUnavailableError = TicketUnavailableError;
 exports.cookieHeader = cookieHeader;
 exports.createJwksCache = createJwksCache;
 exports.createSsoClient = createSsoClient;
+exports.createTicketClient = createTicketClient;
 exports.createTicketVerifier = createTicketVerifier;
+exports.fetchTicket = fetchTicket;
 exports.loadSsoConfig = loadSsoConfig;
 exports.memoryTokenStore = memoryTokenStore;
 exports.readCookie = readCookie;