@deque/axe-auth 0.0.1-skeleton → 1.1.0-next.0269a5dd

package/dist/oauth/tokenResponse.js

@@ -0,0 +1,121 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.throwTokenEndpointError = throwTokenEndpointError;
+exports.parseTokenResponse = parseTokenResponse;
+const errors_1 = require("./errors");
+const predicates_1 = require("./predicates");
+// RFC 6749 §5.1 describes `expires_in` as "the lifetime in seconds"
+// without pinning the JSON type, and some providers historically send
+// numeric strings. Accept both; reject anything non-positive or
+// non-finite.
+function parseExpiresIn(v) {
+    if (typeof v === "number" && Number.isFinite(v) && v > 0)
+        return v;
+    if (typeof v === "string") {
+        const n = Number(v);
+        if (Number.isFinite(n) && n > 0)
+            return n;
+    }
+    return null;
+}
+function parseErrorBody(body) {
+    let parsed;
+    try {
+        parsed = JSON.parse(body);
+    }
+    catch {
+        return {};
+    }
+    if (parsed === null || typeof parsed !== "object")
+        return {};
+    const raw = parsed;
+    return {
+        error: (0, predicates_1.isNonEmptyString)(raw.error) ? raw.error : undefined,
+        description: (0, predicates_1.isNonEmptyString)(raw.error_description)
+            ? raw.error_description
+            : undefined,
+    };
+}
+/**
+ * Reads a non-2xx response body and throws
+ * `OAuthFlowError("TOKEN_EXCHANGE_FAILED", …)` with the OAuth
+ * `error` / `error_description` surfaced in both message and details
+ * when present. Shared by both the authorization-code exchange and
+ * refresh-token paths since the error contract is identical.
+ *
+ * @param context Short human-readable description of which call
+ *   failed ("Token exchange", "Token refresh", etc.). Appears in the
+ *   error message.
+ */
+async function throwTokenEndpointError(response, context) {
+    const body = await response.text().catch(() => "");
+    const { error, description } = parseErrorBody(body);
+    const suffix = error
+        ? description
+            ? `: ${error}: ${description}`
+            : `: ${error}`
+        : "";
+    const details = {};
+    if (error)
+        details.error = error;
+    if (description)
+        details.error_description = description;
+    throw new errors_1.OAuthFlowError("TOKEN_EXCHANGE_FAILED", `${context} failed with HTTP ${response.status}${suffix}`, Object.keys(details).length > 0 ? { details } : undefined);
+}
+/**
+ * Parses a 2xx response body from an RFC 6749 §5.1 token endpoint
+ * (authorization-code exchange, refresh-token grant, etc.) into a
+ * `TokenSet`. Validates the required shape (`access_token`,
+ * `expires_in`, Bearer `token_type`) and converts the relative
+ * `expires_in` into an absolute `expiresAt` using `issuedAt`.
+ *
+ * @param response The HTTP response (must be 2xx; caller handles
+ *   error statuses via `throwTokenEndpointError`).
+ * @param issuedAt The timestamp captured just before the network
+ *   call. Slightly conservative — the token actually expires
+ *   `expires_in` seconds from when the server issued it, so the
+ *   effective usable window is `expires_in - RTT`, which errs toward
+ *   "expires sooner" rather than "expires later."
+ * @param endpointURL URL used for error messages.
+ */
+async function parseTokenResponse(response, issuedAt, endpointURL) {
+    let parsed;
+    try {
+        parsed = await response.json();
+    }
+    catch (cause) {
+        throw new errors_1.OAuthFlowError("TOKEN_EXCHANGE_FAILED", `Token endpoint at ${endpointURL} returned a non-JSON response`, { cause });
+    }
+    if (parsed === null || typeof parsed !== "object") {
+        throw new errors_1.OAuthFlowError("TOKEN_EXCHANGE_FAILED", `Token endpoint at ${endpointURL} returned a non-object response`);
+    }
+    const raw = parsed;
+    if (!(0, predicates_1.isNonEmptyString)(raw.access_token)) {
+        throw new errors_1.OAuthFlowError("TOKEN_EXCHANGE_FAILED", `Token response missing 'access_token'`);
+    }
+    const expiresIn = parseExpiresIn(raw.expires_in);
+    if (expiresIn === null) {
+        throw new errors_1.OAuthFlowError("TOKEN_EXCHANGE_FAILED", `Token response missing or has invalid 'expires_in'`);
+    }
+    // RFC 6749 §5.1: token_type is REQUIRED. We only speak Bearer;
+    // DPoP / MAC / other proof-of-possession types need request-side
+    // support we don't implement, and silently treating them as Bearer
+    // would send tokens in the wrong header with unclear semantics.
+    if (!(0, predicates_1.isNonEmptyString)(raw.token_type)) {
+        throw new errors_1.OAuthFlowError("TOKEN_EXCHANGE_FAILED", `Token response missing required 'token_type'`);
+    }
+    if (raw.token_type.toLowerCase() !== "bearer") {
+        throw new errors_1.OAuthFlowError("TOKEN_EXCHANGE_FAILED", `Unsupported token_type '${raw.token_type}'; this library only handles Bearer.`);
+    }
+    const tokens = {
+        accessToken: raw.access_token,
+        expiresAt: issuedAt + expiresIn * 1000,
+    };
+    if ((0, predicates_1.isNonEmptyString)(raw.refresh_token)) {
+        tokens.refreshToken = raw.refresh_token;
+    }
+    if ((0, predicates_1.isNonEmptyString)(raw.scope)) {
+        tokens.grantedScope = raw.scope;
+    }
+    return tokens;
+}

package/dist/oauth/tokenStore.d.ts

@@ -0,0 +1,124 @@
+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;
+    /**
+     * Originating axe server (walnut) URL the user supplied (or the
+     * SaaS prod default) at login.
+     */
+    walnutURL: string;
+}
+/**
+ * Outcome of a `TokenStore.load()` call.
+ *
+ * Note on downgrades: the migrator chain only walks *forward*. A user
+ * who downgrades `axe-auth` to a release that predates a schema bump
+ * will see `version-mismatch` on any blob written by the newer
+ * release, even if the change was strictly additive. That is the safe
+ * default for a credentials blob — the older version cannot vouch for
+ * the meaning of fields it has never seen. Callers hitting this case
+ * should treat it as "re-authenticate" rather than attempting to
+ * parse an unknown future shape.
+ */
+export type LoadResult = {
+    ok: true;
+    entry: StoredEntry;
+} | {
+    ok: false;
+    reason: "empty";
+} | {
+    ok: false;
+    reason: "corrupt";
+} | {
+    ok: false;
+    reason: "version-mismatch";
+    storedVersion: number;
+};
+/** Persistence layer for an OAuth `StoredEntry`. */
+export interface TokenStore {
+    /** Write-through save. Replaces any previously stored entry. */
+    save(entry: StoredEntry): Promise<void>;
+    /**
+     * 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 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 entry. No-op if none is present. */
+    clear(): Promise<void>;
+}
+/**
+ * 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 declare function parseAndMigrateBlob(raw: string | null, expectedVersion?: number, migrators?: ReadonlyMap<number, (old: unknown) => unknown | null>): BlobChainResult;
+/**
+ * Returns a per-platform hint appended to keychain error messages so
+ * users see actionable guidance for their OS instead of generic or
+ * Linux-only advice. Exported (but not re-exported from the package
+ * index) so tests can exercise each branch without mocking
+ * `process.platform`.
+ */
+export declare function platformKeyringHint(platform?: NodeJS.Platform): string;
+/**
+ * `TokenStore` backed by the operating system's native keychain via
+ * `@napi-rs/keyring` (macOS Keychain, Windows Credential Manager, Linux
+ * 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(entryFactory?: KeyringEntryFactory);
+    save(entry: StoredEntry): Promise<void>;
+    load(): Promise<LoadResult>;
+    clear(): Promise<void>;
+}

package/dist/oauth/tokenStore.js

@@ -0,0 +1,223 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.KeyringTokenStore = exports.STORED_BLOB_VERSION = void 0;
+exports.parseAndMigrateBlob = parseAndMigrateBlob;
+exports.platformKeyringHint = platformKeyringHint;
+const errors_1 = require("./errors");
+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
+ * 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)],
+]);
+// 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.`);
+    }
+}
+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 &&
+        // 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") &&
+        typeof b.issuerURL === "string" &&
+        typeof b.clientId === "string" &&
+        typeof b.allowInsecureIssuer === "boolean" &&
+        typeof b.walnutURL === "string" &&
+        b.walnutURL.length > 0);
+}
+function blobToEntry(blob) {
+    const tokens = {
+        accessToken: blob.accessToken,
+        expiresAt: blob.expiresAt,
+    };
+    if (blob.refreshToken)
+        tokens.refreshToken = blob.refreshToken;
+    return {
+        tokens,
+        issuerURL: blob.issuerURL,
+        clientId: blob.clientId,
+        allowInsecureIssuer: blob.allowInsecureIssuer,
+        walnutURL: blob.walnutURL,
+    };
+}
+function entryToBlob(entry) {
+    const blob = {
+        v: exports.STORED_BLOB_VERSION,
+        accessToken: entry.tokens.accessToken,
+        expiresAt: entry.tokens.expiresAt,
+        issuerURL: entry.issuerURL,
+        clientId: entry.clientId,
+        allowInsecureIssuer: entry.allowInsecureIssuer,
+        walnutURL: entry.walnutURL,
+    };
+    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) {
+    const causeMessage = cause instanceof Error ? cause.message : String(cause);
+    throw new errors_1.OAuthFlowError("KEYRING_UNAVAILABLE", `System keychain ${op} failed: ${causeMessage}. ${platformKeyringHint()}`, { cause });
+}
+/**
+ * Returns a per-platform hint appended to keychain error messages so
+ * users see actionable guidance for their OS instead of generic or
+ * Linux-only advice. Exported (but not re-exported from the package
+ * index) so tests can exercise each branch without mocking
+ * `process.platform`.
+ */
+function platformKeyringHint(platform = process.platform) {
+    switch (platform) {
+        case "darwin":
+            return "On macOS this usually means Keychain Access denied or cancelled the prompt.";
+        case "win32":
+            return "On Windows this usually means Credential Manager rejected the operation.";
+        case "linux":
+            return "On Linux this usually means no D-Bus Secret Service is running (e.g. GNOME Keyring or KWallet).";
+        default:
+            return `Underlying platform: ${platform}.`;
+    }
+}
+/**
+ * `TokenStore` backed by the operating system's native keychain via
+ * `@napi-rs/keyring` (macOS Keychain, Windows Credential Manager, Linux
+ * 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(entryFactory = keyringBinding_1.defaultEntryFactory) {
+        this.#entry = entryFactory(SERVICE_NAME, ACCOUNT_NAME);
+    }
+    async save(entry) {
+        try {
+            this.#entry.setPassword(JSON.stringify(entryToBlob(entry)));
+        }
+        catch (cause) {
+            wrapKeyringError("write", cause);
+        }
+    }
+    async load() {
+        let raw;
+        try {
+            raw = this.#entry.getPassword();
+        }
+        catch (cause) {
+            wrapKeyringError("read", cause);
+        }
+        const chain = parseAndMigrateBlob(raw);
+        if (!chain.ok)
+            return chain;
+        if (!isLatestBlob(chain.blob))
+            return { ok: false, reason: "corrupt" };
+        return { ok: true, entry: blobToEntry(chain.blob) };
+    }
+    async clear() {
+        try {
+            this.#entry.deletePassword();
+        }
+        catch (cause) {
+            wrapKeyringError("delete", cause);
+        }
+    }
+}
+exports.KeyringTokenStore = KeyringTokenStore;

package/dist/userAgent.d.ts

@@ -0,0 +1,12 @@
+/**
+ * `User-Agent` header value sent on all outbound requests, per
+ * Service Development Standards §4.4.
+ *
+ * Format: `axe-auth/v<package-version>` (e.g. `axe-auth/v1.0.2`).
+ *
+ * The npm scope (`@deque/`) is deliberately omitted from the wire format:
+ * `@` and `/` are not valid `tchar` per RFC 9110 §5.6.2, so a token like
+ * `@deque/axe-auth` would make the User-Agent malformed and risk WAF
+ * rejection (e.g. OWASP CRS rule 920330).
+ */
+export declare const USER_AGENT: string;

package/dist/userAgent.js

@@ -0,0 +1,18 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.USER_AGENT = void 0;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const pkg = JSON.parse((0, node_fs_1.readFileSync)((0, node_path_1.join)(__dirname, "..", "package.json"), "utf-8"));
+/**
+ * `User-Agent` header value sent on all outbound requests, per
+ * Service Development Standards §4.4.
+ *
+ * Format: `axe-auth/v<package-version>` (e.g. `axe-auth/v1.0.2`).
+ *
+ * The npm scope (`@deque/`) is deliberately omitted from the wire format:
+ * `@` and `/` are not valid `tchar` per RFC 9110 §5.6.2, so a token like
+ * `@deque/axe-auth` would make the User-Agent malformed and risk WAF
+ * rejection (e.g. OWASP CRS rule 920330).
+ */
+exports.USER_AGENT = `axe-auth/v${pkg.version}`;