@faable/auth-sdk 2.5.96 → 2.6.0

package/.github/workflows/release.yml

@@ -24,6 +24,10 @@ jobs:
           node-version: lts/*
       - run: npm ci
       - run: npm run build
+      # Fails the build if the version sentinels are not in dist/ verbatim
+      # (the release replacement would miss them and the SDK would ship
+      # anonymous) or if anything in dist/ imports `node:*` (browser-unsafe).
+      - run: npm run test:pack
       - run: npm run release
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

package/.releaserc

@@ -18,6 +18,27 @@
   "repositoryUrl": "https://x-access-token:${GITHUB_TOKEN}@github.com/faablecloud/auth-sdk.git",
   "plugins": [
     "@semantic-release/commit-analyzer",
+    [
+      "semantic-release-replace-plugin",
+      {
+        "replacements": [
+          {
+            "files": [
+              "dist/*.js"
+            ],
+            "from": "0.0.0-dev",
+            "to": "${nextRelease.version}"
+          },
+          {
+            "files": [
+              "dist/*.js"
+            ],
+            "from": "0000000dev",
+            "to": "${nextRelease.gitHead.slice(0, 7)}"
+          }
+        ]
+      }
+    ],
     "@semantic-release/release-notes-generator",
     [
       "@semantic-release/npm",

package/README.md

@@ -2,7 +2,7 @@
   <a href="https://faable.com">
     <h1 align="center">Faable Auth SDK</h1>
   </a>
-  <p align="center">Server-side client for the FaableAuth administrative REST API.</p>
+  <p align="center">Client for the FaableAuth REST API — management from a server, session and login flows from a browser or CLI.</p>
 </p>
 
 <p align="center">
@@ -11,9 +11,22 @@
   </a>
 </p>
 
-Programmatically manage FaableAuth users, teams, connections and clients through the FaableAuth REST API.
+Programmatically manage FaableAuth users, teams, connections and clients through the FaableAuth REST API — and, with the right strategy, call the tenant's session and login endpoints from a browser or a CLI.
 
-> ⚠️ **Server-side only.** This SDK uses administrative credentials. Never ship it to a browser or any untrusted runtime.
+> ⚠️ **Where it can run depends on the credential, not on the package.** The
+> SDK itself has no Node-only dependencies and bundles for the browser. What
+> you must never ship to a browser or any untrusted runtime is a
+> **`client_secret`** or an **API key** — those grant management scopes over
+> the whole tenant. A user's own bearer token or the browser's session cookie
+> only grant what that user can do, and those are fine client-side.
+
+| Strategy                | Credential                        | Grants                                                            | Where                                   |
+| ----------------------- | --------------------------------- | ----------------------------------------------------------------- | --------------------------------------- |
+| `authClientCredentials` | `client_id` + **`client_secret`** | The management scopes of the client (full catalog unless narrowed) | **Server only**                         |
+| `authApikey`            | **API key** (`fak_…`)             | The management scopes of the key                                  | **Server only**                         |
+| `authBearer`            | A token the caller already holds  | Whatever that token's scopes and subject allow                    | Anywhere the token itself may live      |
+| `authCookie`            | The browser's session cookie      | The signed-in user's own session (`/me`, MFA, passkeys…)          | Browser, same-origin with the auth host |
+| _(none)_                | —                                 | Public endpoints only (login, passwordless start, device flow…)    | Anywhere                                |
 
 ---
 
@@ -76,15 +89,89 @@ const api = FaableAuthApi.create({
 });
 ```
 
+### Bearer token
+
+For a token you already hold — a user's access token in a CLI, a token minted
+elsewhere. The SDK does not mint or refresh it; whoever owns the token does.
+`token` may be a getter (sync or async): it is consulted on **every** request,
+so a getter that returns the current token keeps a long-lived client correct
+when the token rotates.
+
+```ts
+import { FaableAuthApi, authBearer } from "@faable/auth-sdk";
+
+const api = FaableAuthApi.create({
+  domain: "https://<your-account>.auth.faable.link",
+  authStrategy: authBearer,
+  auth: { token: () => session.accessToken },
+});
+```
+
+What the calls may do is whatever the token's subject and scopes allow — a
+user token reaches the user's own resources, a management token reaches the
+management API.
+
+### Session cookie (browser)
+
+For pages served under the tenant's auth host that authenticate with the
+browser's session cookie (the hosted login pages: `/me`, MFA, passkeys). No
+config: the browser attaches the cookie itself; the strategy makes the request
+`withCredentials` so it also does cross-origin, where the auth server must
+allow the page's origin for credentials.
+
+```ts
+import { FaableAuthApi, authCookie } from "@faable/auth-sdk";
+
+const api = FaableAuthApi.create({
+  domain: "https://<your-account>.auth.faable.link",
+  authStrategy: authCookie,
+});
+```
+
+### No credentials
+
+Omit `auth` and `authStrategy` and the client is anonymous — right for the
+public endpoints (login, `/passwordless/start`, the device flow, OIDC
+discovery). Those are not on the generated client; call them through the
+fetcher:
+
+```ts
+const api = FaableAuthApi.create({ domain: "https://<your-account>.auth.faable.link" });
+await api.fetcher.post("/passwordless/start", { email, client_id });
+```
+
+### Identifying your integration
+
+Every request carries `x-faable-client: auth-sdk/<version>+<sha>` so the
+auth server can attribute traffic. An app that wraps the SDK can report as
+itself instead — the value you pass replaces the default, on data calls and on
+the token request alike:
+
+```ts
+FaableAuthApi.create({ domain, clientInfo: { client: "my-app/1.4.0", name: "my-app" } });
+```
+
+### Per-call options
+
+Every fetcher method takes `timeout`, `responseType` and `retry` for that one
+call. Retries only ever apply to GET (a replayed write could duplicate a
+resource), and `timeout` and `retry` multiply — a short deadline on a hot path
+wants `retry: false` next to it:
+
+```ts
+await api.fetcher.get(`/user/${id}`, { timeout: 800, retry: false });
+```
+
 ### Constructor options
 
 | Option         | Type                                  | Description                                                                                                                  |
 | -------------- | ------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
 | `domain`       | string                                | **Required.** The account host to target, e.g. `https://<your-account>.auth.faable.link`. No default. The protocol is optional — `<your-account>.auth.faable.link` and `https://<your-account>.auth.faable.link` are equivalent. |
-| `authStrategy` | strategy builder                      | Auth strategy (`authClientCredentials` \| `authApikey`), re-exported from `@faable/auth-sdk`. Defaults to `authClientCredentials`. |
+| `authStrategy` | strategy builder                      | Auth strategy (`authClientCredentials` \| `authApikey` \| `authBearer` \| `authCookie`), re-exported from `@faable/auth-sdk`. Defaults to `authClientCredentials` when `auth` is given; anonymous when neither is. |
 | `auth`         | config                                | Config for the chosen strategy. Its shape is inferred from `authStrategy` (e.g. `{ client_id, client_secret }`).            |
 | `debug`        | boolean                               | Enables verbose logging in the underlying fetcher.                                                                          |
 | `headers`      | `{ team_id?; account_id? }`           | Advanced / testing escape hatch — target `domain` but have the server resolve a different team/account (sent as `x-faable-team` / `x-faableauth-account`). |
+| `clientInfo`   | `{ client?; name?; instance? }`       | How this integration identifies itself (`x-faable-client` / `x-faable-instance`). `client` replaces the SDK's own `auth-sdk/<version>+<sha>`. |
 
 ---
 

package/dist/FaableAuthApi.js

@@ -2,7 +2,7 @@ import { getDomain, isPlainObject, requireId } from "./helpers.js";
 import { FaableApiError } from "./error_handler.js";
 import { GeneratedFaableAuthApi } from "./api/generated-client.js";
 import { authClientCredentials } from "@faable/sdk-base";
-import { version } from "./version.js";
+import { SDK_CLIENT } from "./version.js";
 // auth-sdk exists to drive the Faable management API, so a client_credentials
 // client should "just work" against it from `domain` alone. The management API
 // audience is `faable:management:<account_id>`, where `<account_id>` is this
@@ -67,23 +67,27 @@ export class FaableAuthApi extends GeneratedFaableAuthApi {
             ...params,
             auth,
             // Identify ourselves as a first-party client (`x-faable-client:
-            // auth-sdk/<version>`, surfaced as the `client`/`client_version` tags),
-            // and forward any consumer-supplied `name`/`instance` for per-replica
-            // attribution. Routing this through `clientInfo` makes it ride on the
-            // `/oauth/token` call too (sdk-base stamps both fetchers from the same
-            // identity). A caller-set `clientInfo.client` still wins.
+            // auth-sdk/<version>+<sha>`, surfaced as the `client`/`client_version`/
+            // `client_sha` tags), and forward any consumer-supplied `name`/`instance`
+            // for per-replica attribution. Routing this through `clientInfo` makes
+            // it ride on the `/oauth/token` call too (sdk-base stamps both fetchers
+            // from the same identity). A caller-set `clientInfo.client` wins — the
+            // hosted login pages and the CLI wrap this SDK and must report as
+            // themselves, not as auth-sdk.
+            //
+            // Nothing is set as a static fetcher header any more: sdk-base gives
+            // explicit `fetcher.headers` precedence over `clientInfo`, so the old
+            // backward-compat copy of this value silently overrode every consumer's
+            // `clientInfo.client` (and left `/oauth/token` reporting a different
+            // client than the data calls). The sdk-base this package requires has
+            // honoured `clientInfo` since 1.5.x, so the fallback had no job left.
             clientInfo: {
-                client: `auth-sdk/${version}`,
+                client: SDK_CLIENT,
                 ...params?.clientInfo,
             },
             fetcher: {
                 ...params?.fetcher,
                 headers: {
-                    // Also set `x-faable-client` as a static fetcher header for
-                    // backward-compat: if this runs against an older @faable/sdk-base
-                    // that ignores `clientInfo`, data requests still carry it (only the
-                    // new `/oauth/token` attribution needs the newer sdk-base).
-                    "x-faable-client": `auth-sdk/${version}`,
                     ...params?.fetcher?.headers,
                     ...(params?.headers?.team_id && {
                         "x-faable-team": params.headers.team_id,

package/dist/index.d.ts

@@ -1,6 +1,7 @@
 export * from "./FaableAuthApi.js";
+export { SDK_CLIENT, commit, version } from "./version.js";
 export * from "./api/generated-client.js";
 export * from "./api/api-types.js";
 export * from "./api/types.js";
-export { authClientCredentials, authApikey } from "@faable/sdk-base";
-export type { ApiParams, ClientCredentialsConfig, ApikeyConfig, AuthStrategy, AuthStrategyBuilder, AuthStrategyContext, } from "@faable/sdk-base";
+export { authClientCredentials, authApikey, authBearer, authCookie, } from "@faable/sdk-base";
+export type { ApiParams, ClientCredentialsConfig, ApikeyConfig, BearerConfig, RetryConfig, Fetcher, FetcherConfig, FetcherRequestParams, AuthStrategy, AuthStrategyBuilder, AuthStrategyContext, } from "@faable/sdk-base";

package/dist/index.js

@@ -1,8 +1,9 @@
 export * from "./FaableAuthApi.js";
+export { SDK_CLIENT, commit, version } from "./version.js";
 export * from "./api/generated-client.js";
 export * from "./api/api-types.js";
 export * from "./api/types.js";
 // Re-export the auth strategies (and their config/types) from
 // @faable/sdk-base so consumers depend on @faable/auth-sdk ONLY — sdk-base
 // stays a transitive dependency and no app needs to import it directly.
-export { authClientCredentials, authApikey } from "@faable/sdk-base";
+export { authClientCredentials, authApikey, authBearer, authCookie, } from "@faable/sdk-base";

package/dist/version.d.ts

@@ -1,2 +1,3 @@
-declare const version: string;
-export { version };
+export declare const version = "0.0.0-dev";
+export declare const commit = "0000000dev";
+export declare const SDK_CLIENT = "auth-sdk/0.0.0-dev+0000000dev";

package/dist/version.js

@@ -1,9 +1,23 @@
-import { createRequire } from "node:module";
-// Read the published package version at runtime. semantic-release bumps
-// package.json at publish time (after `npm run build`), so a build-time
-// constant would always be stale; reading it from the installed package
-// instead always reflects the real version. From dist/version.js,
-// "../package.json" resolves to the package root.
-const require = createRequire(import.meta.url);
-const { version } = require("../package.json");
-export { version };
+// Both constants are replaced at release time by the
+// `semantic-release-replace-plugin` entries in `.releaserc`, which rewrite
+// every occurrence in `dist/*.js` with the version and commit being published.
+// `tests/pack/verify-pack.mjs` fails the build if either sentinel is missing
+// from the packed output, so a build can never ship anonymous.
+//
+// Why not read package.json at runtime: the previous `createRequire` from
+// `node:module` kept this package out of every browser bundle — the hosted
+// login pages could not import the SDK at all. Same pattern as auth-js.
+//
+// The sentinels MUST stay byte-identical to the `from` values in `.releaserc`.
+export const version = "0.0.0-dev";
+// Short git SHA of the released commit. The version dates a build; this names
+// the exact tree, so a canonical log line or an audit entry leads straight to
+// `git show <sha>`. Deliberately NOT hex: an unreleased build (dev, a local
+// link) cannot be mistaken for a real commit — auth only records values that
+// look like a SHA, and this one never will.
+export const commit = "0000000dev";
+// What this SDK writes in `x-faable-client`. Exported for a consumer that
+// builds a strategy on its own (outside `FaableAuthApi`) and still wants the
+// token request attributed — a bare `authClientCredentials` stamps only what
+// it is given.
+export const SDK_CLIENT = `auth-sdk/${version}+${commit}`;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@faable/auth-sdk",
-  "version": "2.5.96",
+  "version": "2.6.0",
   "author": "Marc Pomar <marc@faable.com>",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -10,7 +10,7 @@
   },
   "type": "module",
   "dependencies": {
-    "@faable/sdk-base": "^1.5.5"
+    "@faable/sdk-base": "^1.6.0"
   },
   "devDependencies": {
     "@ava/typescript": "^5.0.0",
@@ -18,9 +18,11 @@
     "@types/node": "^20.10.5",
     "ava": "^6.1.3",
     "dotenv": "^16.4.5",
+    "nock": "^13.5.5",
     "openapi-typescript": "^7.13.0",
     "rimraf": "^6.0.1",
     "semantic-release": "^25.0.3",
+    "semantic-release-replace-plugin": "^1.2.7",
     "tsimp": "^2.0.11",
     "typescript": "^5.3.3"
   },
@@ -30,7 +32,8 @@
     "prebuild": "npm run gentypes",
     "prepublishOnly": "npm run build",
     "test": "ava",
-    "release": "semantic-release"
+    "release": "semantic-release",
+    "test:pack": "node tests/pack/verify-pack.mjs"
   },
   "resolutions": {
     "npm/chalk": "^4.1.2"

package/tests/pack/verify-pack.mjs

@@ -0,0 +1,100 @@
+#!/usr/bin/env node
+// Guard on the PACKED build, run in CI between `npm run build` and the
+// release. Three things that a green unit suite cannot see:
+//
+//  1. The version sentinels are in dist/ byte-identical to `.releaserc`, so
+//     semantic-release's replacement actually hits them. auth-js shipped as
+//     `auth-js/0.0.0` for months because its sentinel and its `.releaserc`
+//     disagreed — the rewrite hit a banner comment and nothing else.
+//  2. Nothing in dist/ imports `node:*`. This package has to load in a browser
+//     bundle (the hosted login pages); a `createRequire` from `node:module`
+//     is exactly what kept it out until now.
+//  3. The identity header on the wire: the default is `auth-sdk/<sentinels>`,
+//     and a consumer's `clientInfo.client` REPLACES it (the old static header
+//     used to override it silently).
+import { execSync } from "node:child_process";
+import { mkdtempSync, readFileSync, readdirSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const ROOT = resolve(fileURLToPath(import.meta.url), "../../..");
+const run = (cmd, opts = {}) => execSync(cmd, { stdio: "inherit", ...opts });
+const capture = (cmd, opts = {}) => execSync(cmd, { encoding: "utf8", ...opts }).trim();
+const fail = (msg, ...rest) => {
+  console.error("✖", msg, ...rest);
+  process.exit(1);
+};
+
+console.log("→ Building dist/");
+run("npm run build", { cwd: ROOT });
+
+// 1. Sentinels, verbatim, straight from .releaserc so the two cannot drift.
+const releaserc = JSON.parse(readFileSync(join(ROOT, ".releaserc"), "utf8"));
+const replacePlugin = releaserc.plugins.find(
+  (p) => Array.isArray(p) && p[0] === "semantic-release-replace-plugin",
+);
+if (!replacePlugin) fail(".releaserc has no semantic-release-replace-plugin entry");
+const versionJs = readFileSync(join(ROOT, "dist/version.js"), "utf8");
+for (const { from } of replacePlugin[1].replacements) {
+  if (!versionJs.includes(from)) {
+    fail(`dist/version.js does not contain the sentinel "${from}" that .releaserc replaces`);
+  }
+}
+console.log("✓ sentinels present in dist/version.js");
+
+// 2. Browser-safety: no node: specifiers anywhere in the published JS.
+const jsFiles = (dir) =>
+  readdirSync(dir, { withFileTypes: true }).flatMap((e) =>
+    e.isDirectory() ? jsFiles(join(dir, e.name)) : e.name.endsWith(".js") ? [join(dir, e.name)] : [],
+  );
+for (const file of jsFiles(join(ROOT, "dist"))) {
+  const src = readFileSync(file, "utf8");
+  const hit = src.match(/from\s+["']node:[^"']+["']|require\(["']node:|createRequire\(/);
+  if (hit) fail(`${file.replace(ROOT + "/", "")} is not browser-safe: ${hit[0]}`);
+}
+console.log("✓ dist/ has no node: imports");
+
+// 3. Pack, install into a clean consumer, look at the wire.
+const tmp = mkdtempSync(join(tmpdir(), "faable-auth-sdk-pack-"));
+try {
+  const tarball = join(ROOT, capture("npm pack --silent --pack-destination .", { cwd: ROOT }));
+  writeFileSync(
+    join(tmp, "package.json"),
+    JSON.stringify({ name: "consumer", version: "0.0.0", type: "module", private: true }, null, 2),
+  );
+  run(`npm install --silent --no-save "${tarball}"`, { cwd: tmp });
+  rmSync(tarball, { force: true });
+
+  const probe = `
+    const mod = await import("@faable/auth-sdk");
+    for (const name of ["FaableAuthApi", "authClientCredentials", "authApikey", "authBearer", "authCookie"]) {
+      if (typeof mod[name] === "undefined") { console.error("Missing export:", name); process.exit(1); }
+    }
+    const seen = [];
+    const adapter = async (config) => { seen.push(config); return { data: {}, status: 200, statusText: "OK", headers: {}, config }; };
+    const header = (i) => seen[i].headers["x-faable-client"] ?? seen[i].headers["X-Faable-Client"];
+
+    const dflt = mod.FaableAuthApi.create({ domain: "https://t.auth.faable.link", fetcher: { adapter } });
+    await dflt.fetcher.get("/me");
+    const expected = "auth-sdk/" + ${JSON.stringify(
+      replacePlugin[1].replacements.map((r) => r.from).join("+"),
+    )};
+    if (header(0) !== expected) { console.error("default x-faable-client must be", expected, "got", header(0)); process.exit(1); }
+    if (header(0).slice("auth-sdk/".length).length > 32) { console.error("version+sha exceeds auth's 32-char budget:", header(0)); process.exit(1); }
+
+    const wrapped = mod.FaableAuthApi.create({ domain: "https://t.auth.faable.link", fetcher: { adapter }, clientInfo: { client: "probe-ui/1.2.3" } });
+    await wrapped.fetcher.get("/me");
+    if (header(1) !== "probe-ui/1.2.3") { console.error("clientInfo.client must replace the default, got", header(1)); process.exit(1); }
+
+    const cookie = mod.FaableAuthApi.create({ domain: "https://t.auth.faable.link", fetcher: { adapter }, authStrategy: mod.authCookie });
+    await cookie.fetcher.get("/me");
+    if (seen[2].withCredentials !== true) { console.error("authCookie must send withCredentials"); process.exit(1); }
+    console.log("✓ wire identity: default", header(0), "| wrapped", header(1), "| cookie withCredentials");
+  `;
+  writeFileSync(join(tmp, "probe.mjs"), probe);
+  run("node probe.mjs", { cwd: tmp });
+} finally {
+  rmSync(tmp, { recursive: true, force: true });
+}
+console.log("✓ pack verified");