@deque/axe-auth 1.1.0-next.907ffbd7 → 1.1.0-next.ac35e028

package/dist/oauth/tokenStore.d.ts

@@ -1,10 +1,27 @@
-import type { TokenSet } from "./tokenExchange";
+import { type KeyringEntryFactory } from "./keyringBinding";
+import type { TokenSet } from "./tokenResponse";
 /**
  * Current on-disk blob schema version. Exported so consumers can
  * display "stored v:N, expected v:M" diagnostics when `load()` returns
  * a `version-mismatch` result.
  */
 export declare const STORED_BLOB_VERSION = 1;
+/**
+ * What `KeyringTokenStore` persists: the OAuth tokens plus the
+ * issuer/client coordinates they were minted against. Carrying the
+ * coordinates inside the entry means a verb can recover its full
+ * config from the keychain alone, with no separate "default issuer"
+ * pointer.
+ */
+export interface StoredEntry {
+    tokens: TokenSet;
+    /** OIDC issuer URL the tokens were minted against. */
+    issuerURL: string;
+    /** OAuth client ID used at login. */
+    clientId: string;
+    /** Whether the original login allowed a non-loopback http issuer. */
+    allowInsecureIssuer: boolean;
+}
 /**
  * Outcome of a `TokenStore.load()` call.
  *
@@ -19,7 +36,7 @@ export declare const STORED_BLOB_VERSION = 1;
  */
 export type LoadResult = {
     ok: true;
-    tokens: TokenSet;
+    entry: StoredEntry;
 } | {
     ok: false;
     reason: "empty";
@@ -31,48 +48,64 @@ export type LoadResult = {
     reason: "version-mismatch";
     storedVersion: number;
 };
-/** Persistence layer for an OAuth `TokenSet`. */
+/** Persistence layer for an OAuth `StoredEntry`. */
 export interface TokenStore {
-    /** Write-through save. Replaces any previously stored tokens. */
-    save(tokens: TokenSet): Promise<void>;
+    /** Write-through save. Replaces any previously stored entry. */
+    save(entry: StoredEntry): Promise<void>;
     /**
-     * Reads the stored tokens and returns a structured result.
+     * Reads the stored entry and returns a structured result.
      *
      * Callers should branch on `result.ok` first. When `ok` is `false`,
-     * `reason` tells them *why* there is no usable `TokenSet`: `empty`
+     * `reason` tells them *why* there is no usable entry: `empty`
      * (nothing stored), `corrupt` (unparseable or shape-invalid), or
      * `version-mismatch` (stored under a schema we cannot migrate from).
      * The library does not emit output on these cases — surfacing them
      * to the user is the caller's responsibility.
      */
     load(): Promise<LoadResult>;
-    /** Removes any stored tokens. No-op if none are present. */
+    /** Removes any stored entry. No-op if none is present. */
     clear(): Promise<void>;
 }
-/** Minimal keyring-entry surface consumed by `KeyringTokenStore`. */
-export interface KeyringEntry {
-    /** Writes the password for this entry. */
-    setPassword(password: string): void;
-    /** Reads the current password, or returns `null` if none is set. */
-    getPassword(): string | null;
-    /** Deletes the password and returns `true` if one existed. */
-    deletePassword(): boolean;
-}
 /**
- * Factory for `KeyringEntry` values. Injection seam for tests;
- * production callers use the default that constructs
- * `@napi-rs/keyring` entries lazily.
+ * Outcome of `parseAndMigrateBlob`: same set of failure reasons as
+ * `LoadResult`, but on success carries the post-migration blob as an
+ * unknown payload. The caller is responsible for shape-validating
+ * that payload against the latest schema.
+ */
+export type BlobChainResult = {
+    ok: true;
+    blob: unknown;
+} | {
+    ok: false;
+    reason: "empty";
+} | {
+    ok: false;
+    reason: "corrupt";
+} | {
+    ok: false;
+    reason: "version-mismatch";
+    storedVersion: number;
+};
+/**
+ * JSON-parses the raw keychain password and walks the migrator chain
+ * until it reaches `expectedVersion`. Exported with `expectedVersion`
+ * and `migrators` parameters only for testing the chain mechanics
+ * against synthetic versions / migrators; production callers use
+ * `KeyringTokenStore.load()`, which feeds in `STORED_BLOB_VERSION`
+ * and `MIGRATORS` and applies the latest-shape check on top.
  */
-export type KeyringEntryFactory = (service: string, account: string) => KeyringEntry;
+export declare function parseAndMigrateBlob(raw: string | null, expectedVersion?: number, migrators?: ReadonlyMap<number, (old: unknown) => unknown | null>): BlobChainResult;
 /**
  * `TokenStore` backed by the operating system's native keychain via
  * `@napi-rs/keyring` (macOS Keychain, Windows Credential Manager, Linux
- * Secret Service). Account is keyed by the normalized issuer URL.
+ * Secret Service). One entry per machine, keyed by a fixed account
+ * name; the blob carries its own issuer/client coordinates so verbs
+ * can recover full config without per-issuer keying.
  */
 export declare class KeyringTokenStore implements TokenStore {
     #private;
-    constructor(issuerURL: string, entryFactory?: KeyringEntryFactory);
-    save(tokens: TokenSet): Promise<void>;
+    constructor(entryFactory?: KeyringEntryFactory);
+    save(entry: StoredEntry): Promise<void>;
     load(): Promise<LoadResult>;
     clear(): Promise<void>;
 }

package/dist/oauth/tokenStore.js

@@ -1,15 +1,24 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.KeyringTokenStore = exports.STORED_BLOB_VERSION = void 0;
-const node_module_1 = require("node:module");
+exports.parseAndMigrateBlob = parseAndMigrateBlob;
 const errors_1 = require("./errors");
-const issuerURL_1 = require("./issuerURL");
-const requireFromHere = (0, node_module_1.createRequire)(__filename);
+const keyringBinding_1 = require("./keyringBinding");
 // On macOS: Keychain generic password item with the service name below.
 // On Windows: Credential Manager entry. On Linux: Secret Service / libsecret.
 // Exposed as a human-readable string because these all surface the service
 // name in OS UIs (Keychain Access, credmgr.exe, seahorse).
 const SERVICE_NAME = "axe-auth";
+// Single keychain entry per machine. The blob it holds is fully
+// self-describing (issuerURL, clientId, allowInsecureIssuer, plus the
+// tokens), so verbs that don't pass `--server` / `--realm` /
+// `--client-id` can resolve their config from the entry.
+//
+// Account name is human-readable so users investigating the entry in
+// macOS Keychain Access (or `secret-tool` on Linux, credmgr on
+// Windows) can tell what it is. Not versioned: the schema version
+// lives inside the blob and migrators handle the upgrade path.
+const ACCOUNT_NAME = "credentials";
 /**
  * Current on-disk blob schema version. Exported so consumers can
  * display "stored v:N, expected v:M" diagnostics when `load()` returns
@@ -32,35 +41,17 @@ exports.STORED_BLOB_VERSION = 1;
 const MIGRATORS = new Map([
 // [1, (v1) => migrateV1ToV2(v1 as StoredBlobV1)],
 ]);
-// Lazy-resolved Entry constructor. Importing @napi-rs/keyring at the
-// top of this module would run its native binding loader at
-// module-load time, throwing before any of our OAuthFlowError code
-// catches it and preventing the module from being imported at all on
-// platforms without a prebuilt. We defer the require into
-// `defaultEntryFactory`, which turns that import-time failure into a
-// `KEYRING_UNAVAILABLE` surfaced on the first `new
-// KeyringTokenStore(...)` call — not on first save/load/clear, since
-// `authorize()` (and similar callers) construct the store eagerly as
-// a default-arg expression. Runtime keychain errors (missing D-Bus
-// Secret Service, macOS Keychain denial, etc.) are a separate
-// concern and surface later, inside save/load/clear.
-let cachedEntryCtor = null;
-function resolveEntryCtor() {
-    if (cachedEntryCtor)
-        return cachedEntryCtor;
-    try {
-        const mod = requireFromHere("@napi-rs/keyring");
-        cachedEntryCtor = mod.Entry;
-        return cachedEntryCtor;
-    }
-    catch (cause) {
-        throw new errors_1.OAuthFlowError("KEYRING_UNAVAILABLE", `Could not load @napi-rs/keyring. A prebuilt native binding for this platform may be missing.`, { cause });
+// Sanity-check the migrator map at module load. Every key must be
+// strictly less than `STORED_BLOB_VERSION` — the chain only walks
+// forward, so a leftover migrator at the current (or future) version
+// would either be unreachable or confuse the loop. Fail-fast so a
+// dev forgetting to remove a stale entry during a version bump
+// notices before shipping.
+for (const fromVersion of MIGRATORS.keys()) {
+    if (fromVersion >= exports.STORED_BLOB_VERSION) {
+        throw new Error(`MIGRATORS contains a key (v${fromVersion}) that is not strictly less than STORED_BLOB_VERSION (${exports.STORED_BLOB_VERSION}). The chain only walks forward; remove stale migrators when bumping the schema version.`);
     }
 }
-const defaultEntryFactory = (service, account) => {
-    const Ctor = resolveEntryCtor();
-    return new Ctor(service, account);
-};
 function getStoredVersion(blob) {
     if (blob === null || typeof blob !== "object")
         return null;
@@ -72,45 +63,109 @@ function isLatestBlob(blob) {
         return false;
     const b = blob;
     return (b.v === exports.STORED_BLOB_VERSION &&
+        // Empty access token is treated as corrupt rather than a usable
+        // credential. `axe-auth token` printing an empty line and exiting
+        // 0 would look like success and silently break downstream.
         typeof b.accessToken === "string" &&
+        b.accessToken.length > 0 &&
         typeof b.expiresAt === "number" &&
-        (b.refreshToken === undefined || typeof b.refreshToken === "string"));
+        (b.refreshToken === undefined || typeof b.refreshToken === "string") &&
+        typeof b.issuerURL === "string" &&
+        typeof b.clientId === "string" &&
+        typeof b.allowInsecureIssuer === "boolean");
 }
-function blobToTokens(blob) {
+function blobToEntry(blob) {
     const tokens = {
         accessToken: blob.accessToken,
         expiresAt: blob.expiresAt,
     };
-    if (blob.refreshToken !== undefined)
+    if (blob.refreshToken)
         tokens.refreshToken = blob.refreshToken;
-    return tokens;
+    return {
+        tokens,
+        issuerURL: blob.issuerURL,
+        clientId: blob.clientId,
+        allowInsecureIssuer: blob.allowInsecureIssuer,
+    };
 }
-function tokensToBlob(tokens) {
+function entryToBlob(entry) {
     const blob = {
         v: exports.STORED_BLOB_VERSION,
-        accessToken: tokens.accessToken,
-        expiresAt: tokens.expiresAt,
+        accessToken: entry.tokens.accessToken,
+        expiresAt: entry.tokens.expiresAt,
+        issuerURL: entry.issuerURL,
+        clientId: entry.clientId,
+        allowInsecureIssuer: entry.allowInsecureIssuer,
     };
-    if (tokens.refreshToken !== undefined)
-        blob.refreshToken = tokens.refreshToken;
+    if (entry.tokens.refreshToken)
+        blob.refreshToken = entry.tokens.refreshToken;
     return blob;
 }
+/**
+ * JSON-parses the raw keychain password and walks the migrator chain
+ * until it reaches `expectedVersion`. Exported with `expectedVersion`
+ * and `migrators` parameters only for testing the chain mechanics
+ * against synthetic versions / migrators; production callers use
+ * `KeyringTokenStore.load()`, which feeds in `STORED_BLOB_VERSION`
+ * and `MIGRATORS` and applies the latest-shape check on top.
+ */
+function parseAndMigrateBlob(raw, expectedVersion = exports.STORED_BLOB_VERSION, migrators = MIGRATORS) {
+    if (raw === null)
+        return { ok: false, reason: "empty" };
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return { ok: false, reason: "corrupt" };
+    }
+    const storedVersion = getStoredVersion(parsed);
+    if (storedVersion === null)
+        return { ok: false, reason: "corrupt" };
+    // Walk the migrator chain until we reach the expected version. A
+    // missing or null-returning migrator means the old blob cannot be
+    // upgraded; surface that so callers can prompt re-auth with a
+    // clear signal instead of silently returning `empty`.
+    let current = parsed;
+    let currentVersion = storedVersion;
+    while (currentVersion !== expectedVersion) {
+        const migrator = migrators.get(currentVersion);
+        if (!migrator) {
+            return { ok: false, reason: "version-mismatch", storedVersion };
+        }
+        const next = migrator(current);
+        if (next === null) {
+            return { ok: false, reason: "version-mismatch", storedVersion };
+        }
+        const nextVersion = getStoredVersion(next);
+        if (nextVersion === null || nextVersion <= currentVersion) {
+            // Migrator output is malformed or didn't advance. Treat the
+            // stored blob as un-migratable rather than loop forever.
+            return { ok: false, reason: "version-mismatch", storedVersion };
+        }
+        current = next;
+        currentVersion = nextVersion;
+    }
+    return { ok: true, blob: current };
+}
 function wrapKeyringError(op, cause) {
     throw new errors_1.OAuthFlowError("KEYRING_UNAVAILABLE", `System keychain ${op} failed. On Linux this usually means no D-Bus Secret Service is running.`, { cause });
 }
 /**
  * `TokenStore` backed by the operating system's native keychain via
  * `@napi-rs/keyring` (macOS Keychain, Windows Credential Manager, Linux
- * Secret Service). Account is keyed by the normalized issuer URL.
+ * Secret Service). One entry per machine, keyed by a fixed account
+ * name; the blob carries its own issuer/client coordinates so verbs
+ * can recover full config without per-issuer keying.
  */
 class KeyringTokenStore {
     #entry;
-    constructor(issuerURL, entryFactory = defaultEntryFactory) {
-        this.#entry = entryFactory(SERVICE_NAME, (0, issuerURL_1.normalizeIssuerURL)(issuerURL));
+    constructor(entryFactory = keyringBinding_1.defaultEntryFactory) {
+        this.#entry = entryFactory(SERVICE_NAME, ACCOUNT_NAME);
     }
-    async save(tokens) {
+    async save(entry) {
         try {
-            this.#entry.setPassword(JSON.stringify(tokensToBlob(tokens)));
+            this.#entry.setPassword(JSON.stringify(entryToBlob(entry)));
         }
         catch (cause) {
             wrapKeyringError("write", cause);
@@ -124,45 +179,12 @@ class KeyringTokenStore {
         catch (cause) {
             wrapKeyringError("read", cause);
         }
-        if (raw === null)
-            return { ok: false, reason: "empty" };
-        let parsed;
-        try {
-            parsed = JSON.parse(raw);
-        }
-        catch {
-            return { ok: false, reason: "corrupt" };
-        }
-        const storedVersion = getStoredVersion(parsed);
-        if (storedVersion === null)
-            return { ok: false, reason: "corrupt" };
-        // Walk the migrator chain until we reach the current version. A
-        // missing or null-returning migrator means the old blob cannot be
-        // upgraded; surface that so callers can prompt re-auth with a
-        // clear signal instead of silently returning `empty`.
-        let current = parsed;
-        let currentVersion = storedVersion;
-        while (currentVersion !== exports.STORED_BLOB_VERSION) {
-            const migrator = MIGRATORS.get(currentVersion);
-            if (!migrator) {
-                return { ok: false, reason: "version-mismatch", storedVersion };
-            }
-            const next = migrator(current);
-            if (next === null) {
-                return { ok: false, reason: "version-mismatch", storedVersion };
-            }
-            const nextVersion = getStoredVersion(next);
-            if (nextVersion === null || nextVersion <= currentVersion) {
-                // Migrator output is malformed or didn't advance. Treat the
-                // stored blob as un-migratable rather than loop forever.
-                return { ok: false, reason: "version-mismatch", storedVersion };
-            }
-            current = next;
-            currentVersion = nextVersion;
-        }
-        if (!isLatestBlob(current))
+        const chain = parseAndMigrateBlob(raw);
+        if (!chain.ok)
+            return chain;
+        if (!isLatestBlob(chain.blob))
             return { ok: false, reason: "corrupt" };
-        return { ok: true, tokens: blobToTokens(current) };
+        return { ok: true, entry: blobToEntry(chain.blob) };
     }
     async clear() {
         try {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deque/axe-auth",
-  "version": "1.1.0-next.907ffbd7",
+  "version": "1.1.0-next.ac35e028",
   "description": "CLI authentication utility for Deque services",
   "license": "SEE LICENSE IN LICENSE",
   "type": "commonjs",
@@ -21,7 +21,9 @@
     "node": ">=22.13.0"
   },
   "dependencies": {
-    "@napi-rs/keyring": "^1.2.0"
+    "@napi-rs/keyring": "^1.2.0",
+    "remove-trailing-slash": "^0.1.1",
+    "ts-dedent": "^2.2.0"
   },
   "devDependencies": {
     "@types/node": "^22.13.10",
@@ -35,6 +37,7 @@
     "coverage": "c8 pnpm test",
     "register-dev-client": "tsx scripts/registerDevClient.ts",
     "smoke-authorize": "tsx scripts/smokeAuthorize.ts",
+    "smoke-cli": "tsx scripts/smokeCLI.ts",
     "manual-authorize": "tsx scripts/manualAuthorize.ts"
   }
 }