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

package/dist/oauth/tokenStore.js

@@ -0,0 +1,176 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.KeyringTokenStore = exports.STORED_BLOB_VERSION = void 0;
+const node_module_1 = require("node:module");
+const errors_1 = require("./errors");
+const issuerURL_1 = require("./issuerURL");
+const requireFromHere = (0, node_module_1.createRequire)(__filename);
+// 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";
+/**
+ * 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.
+ */
+exports.STORED_BLOB_VERSION = 1;
+/**
+ * Migrators upgrade an older blob to the next version up. Walked by
+ * `load()` until the stored blob reaches `STORED_BLOB_VERSION`.
+ *
+ * A migrator returns `null` when the bump cannot be inferred from the
+ * old shape (e.g. a new required field with no derivable default); the
+ * caller then sees `{ ok: false, reason: "version-mismatch" }` and
+ * decides whether to re-auth, prompt, or preserve the old blob.
+ *
+ * Each migrator is responsible for taking `vN` → `vN+1`. To skip a
+ * version deliberately, register a migrator that returns `null` for
+ * that `fromVersion`.
+ */
+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 });
+    }
+}
+const defaultEntryFactory = (service, account) => {
+    const Ctor = resolveEntryCtor();
+    return new Ctor(service, account);
+};
+function getStoredVersion(blob) {
+    if (blob === null || typeof blob !== "object")
+        return null;
+    const v = blob.v;
+    return typeof v === "number" && Number.isInteger(v) && v > 0 ? v : null;
+}
+function isLatestBlob(blob) {
+    if (blob === null || typeof blob !== "object")
+        return false;
+    const b = blob;
+    return (b.v === exports.STORED_BLOB_VERSION &&
+        typeof b.accessToken === "string" &&
+        typeof b.expiresAt === "number" &&
+        (b.refreshToken === undefined || typeof b.refreshToken === "string"));
+}
+function blobToTokens(blob) {
+    const tokens = {
+        accessToken: blob.accessToken,
+        expiresAt: blob.expiresAt,
+    };
+    if (blob.refreshToken !== undefined)
+        tokens.refreshToken = blob.refreshToken;
+    return tokens;
+}
+function tokensToBlob(tokens) {
+    const blob = {
+        v: exports.STORED_BLOB_VERSION,
+        accessToken: tokens.accessToken,
+        expiresAt: tokens.expiresAt,
+    };
+    if (tokens.refreshToken !== undefined)
+        blob.refreshToken = tokens.refreshToken;
+    return blob;
+}
+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.
+ */
+class KeyringTokenStore {
+    #entry;
+    constructor(issuerURL, entryFactory = defaultEntryFactory) {
+        this.#entry = entryFactory(SERVICE_NAME, (0, issuerURL_1.normalizeIssuerURL)(issuerURL));
+    }
+    async save(tokens) {
+        try {
+            this.#entry.setPassword(JSON.stringify(tokensToBlob(tokens)));
+        }
+        catch (cause) {
+            wrapKeyringError("write", cause);
+        }
+    }
+    async load() {
+        let raw;
+        try {
+            raw = this.#entry.getPassword();
+        }
+        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))
+            return { ok: false, reason: "corrupt" };
+        return { ok: true, tokens: blobToTokens(current) };
+    }
+    async clear() {
+        try {
+            this.#entry.deletePassword();
+        }
+        catch (cause) {
+            wrapKeyringError("delete", cause);
+        }
+    }
+}
+exports.KeyringTokenStore = KeyringTokenStore;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deque/axe-auth",
-  "version": "1.1.0-next.789db6ed",
+  "version": "1.1.0-next.907ffbd7",
   "description": "CLI authentication utility for Deque services",
   "license": "SEE LICENSE IN LICENSE",
   "type": "commonjs",
@@ -20,13 +20,21 @@
   "engines": {
     "node": ">=22.13.0"
   },
+  "dependencies": {
+    "@napi-rs/keyring": "^1.2.0"
+  },
   "devDependencies": {
     "@types/node": "^22.13.10",
+    "c8": "^10.1.3",
     "tsx": "^4.20.6",
     "typescript": "^5.9.3"
   },
   "scripts": {
     "build": "tsc",
-    "test": "tsx --test 'src/**/*.test.ts'"
+    "test": "tsx --test 'src/**/*.test.ts'",
+    "coverage": "c8 pnpm test",
+    "register-dev-client": "tsx scripts/registerDevClient.ts",
+    "smoke-authorize": "tsx scripts/smokeAuthorize.ts",
+    "manual-authorize": "tsx scripts/manualAuthorize.ts"
   }
 }