@claude-flow/security 3.0.0-alpha.9 → 3.0.0

package/dist/oauth/callback-server.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Ephemeral-port localhost callback server for the browser-based OAuth flow
+ * (ADR-306). A minimal single-request HTTP server — deliberately not a full
+ * framework for one GET route that lives for one request and then shuts
+ * down. A TypeScript port of meta-proxy's `src/oauth/callback_server.rs`.
+ *
+ * @module v3/security/oauth/callback-server
+ */
+export interface CallbackResult {
+    code: string | null;
+    state: string | null;
+    error: string | null;
+}
+export declare class CallbackTimeoutError extends Error {
+    constructor();
+}
+export declare class CallbackServer {
+    private readonly server;
+    readonly redirectUri: string;
+    readonly port: number;
+    private constructor();
+    /**
+     * Binds `127.0.0.1:0` (OS-assigned ephemeral port) and returns the server
+     * plus the exact `redirect_uri` to send in the authorize request — must be
+     * the `http://127.0.0.1:<port>/oauth/callback` shape identity's
+     * `validate_redirect_uri` accepts.
+     */
+    static bind(): Promise<CallbackServer>;
+    /**
+     * Waits for exactly one `GET /oauth/callback?...` request, replies with the
+     * browser success page, closes the server, and returns the parsed query
+     * parameters. Times out after `waitForMs` so a login attempt the user
+     * abandons in the browser doesn't hang the CLI forever.
+     */
+    awaitCallback(waitForMs?: number): Promise<CallbackResult>;
+}
+//# sourceMappingURL=callback-server.d.ts.map

package/dist/oauth/callback-server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"callback-server.d.ts","sourceRoot":"","sources":["../../src/oauth/callback-server.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAKH,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;CACtB;AAeD,qBAAa,oBAAqB,SAAQ,KAAK;;CAK9C;AAED,qBAAa,cAAc;IAEvB,OAAO,CAAC,QAAQ,CAAC,MAAM;aACP,WAAW,EAAE,MAAM;aACnB,IAAI,EAAE,MAAM;IAH9B,OAAO;IAMP;;;;;OAKG;WACU,IAAI,IAAI,OAAO,CAAC,cAAc,CAAC;IAa5C;;;;;OAKG;IACG,aAAa,CAAC,SAAS,SAAqB,GAAG,OAAO,CAAC,cAAc,CAAC;CA0B7E"}

package/dist/oauth/callback-server.js

@@ -0,0 +1,86 @@
+/**
+ * Ephemeral-port localhost callback server for the browser-based OAuth flow
+ * (ADR-306). A minimal single-request HTTP server — deliberately not a full
+ * framework for one GET route that lives for one request and then shuts
+ * down. A TypeScript port of meta-proxy's `src/oauth/callback_server.rs`.
+ *
+ * @module v3/security/oauth/callback-server
+ */
+import { createServer } from 'node:http';
+const SUCCESS_PAGE = `<html>
+<body style="background:#0a0a0a; color:#f5f5f5; font-family:sans-serif;
+    display:flex; align-items:center; justify-content:center;
+    height:100vh; margin:0;">
+    <div style="text-align:center;">
+    <h1>&#10003; ruflo login successful</h1>
+    <p>You can close this tab and return to your terminal.</p>
+    </div>
+</body>
+</html>`;
+const DEFAULT_TIMEOUT_MS = 5 * 60 * 1000; // 5 minutes, matches meta-proxy's CALLBACK_TIMEOUT
+export class CallbackTimeoutError extends Error {
+    constructor() {
+        super('timed out waiting for OAuth callback');
+        this.name = 'CallbackTimeoutError';
+    }
+}
+export class CallbackServer {
+    server;
+    redirectUri;
+    port;
+    constructor(server, redirectUri, port) {
+        this.server = server;
+        this.redirectUri = redirectUri;
+        this.port = port;
+    }
+    /**
+     * Binds `127.0.0.1:0` (OS-assigned ephemeral port) and returns the server
+     * plus the exact `redirect_uri` to send in the authorize request — must be
+     * the `http://127.0.0.1:<port>/oauth/callback` shape identity's
+     * `validate_redirect_uri` accepts.
+     */
+    static async bind() {
+        return new Promise((resolve, reject) => {
+            const server = createServer();
+            server.once('error', reject);
+            server.listen(0, '127.0.0.1', () => {
+                server.removeListener('error', reject);
+                const addr = server.address();
+                const redirectUri = `http://127.0.0.1:${addr.port}/oauth/callback`;
+                resolve(new CallbackServer(server, redirectUri, addr.port));
+            });
+        });
+    }
+    /**
+     * Waits for exactly one `GET /oauth/callback?...` request, replies with the
+     * browser success page, closes the server, and returns the parsed query
+     * parameters. Times out after `waitForMs` so a login attempt the user
+     * abandons in the browser doesn't hang the CLI forever.
+     */
+    async awaitCallback(waitForMs = DEFAULT_TIMEOUT_MS) {
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                this.server.close();
+                reject(new CallbackTimeoutError());
+            }, waitForMs);
+            this.server.once('request', (req, res) => {
+                clearTimeout(timer);
+                const url = new URL(req.url ?? '/oauth/callback', 'http://127.0.0.1');
+                const result = {
+                    code: url.searchParams.get('code'),
+                    state: url.searchParams.get('state'),
+                    error: url.searchParams.get('error'),
+                };
+                res.writeHead(200, {
+                    'content-type': 'text/html; charset=utf-8',
+                    connection: 'close',
+                });
+                res.end(SUCCESS_PAGE, () => {
+                    this.server.close();
+                    resolve(result);
+                });
+            });
+        });
+    }
+}
+//# sourceMappingURL=callback-server.js.map

package/dist/oauth/callback-server.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"callback-server.js","sourceRoot":"","sources":["../../src/oauth/callback-server.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,YAAY,EAAe,MAAM,WAAW,CAAC;AAStD,MAAM,YAAY,GAAG;;;;;;;;;QASb,CAAC;AAET,MAAM,kBAAkB,GAAG,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,CAAC,mDAAmD;AAE7F,MAAM,OAAO,oBAAqB,SAAQ,KAAK;IAC7C;QACE,KAAK,CAAC,sCAAsC,CAAC,CAAC;QAC9C,IAAI,CAAC,IAAI,GAAG,sBAAsB,CAAC;IACrC,CAAC;CACF;AAED,MAAM,OAAO,cAAc;IAEN;IACD;IACA;IAHlB,YACmB,MAAc,EACf,WAAmB,EACnB,IAAY;QAFX,WAAM,GAAN,MAAM,CAAQ;QACf,gBAAW,GAAX,WAAW,CAAQ;QACnB,SAAI,GAAJ,IAAI,CAAQ;IAC3B,CAAC;IAEJ;;;;;OAKG;IACH,MAAM,CAAC,KAAK,CAAC,IAAI;QACf,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;YACrC,MAAM,MAAM,GAAG,YAAY,EAAE,CAAC;YAC9B,MAAM,CAAC,IAAI,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;YAC7B,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,WAAW,EAAE,GAAG,EAAE;gBACjC,MAAM,CAAC,cAAc,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;gBACvC,MAAM,IAAI,GAAG,MAAM,CAAC,OAAO,EAAiB,CAAC;gBAC7C,MAAM,WAAW,GAAG,oBAAoB,IAAI,CAAC,IAAI,iBAAiB,CAAC;gBACnE,OAAO,CAAC,IAAI,cAAc,CAAC,MAAM,EAAE,WAAW,EAAE,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC;YAC9D,CAAC,CAAC,CAAC;QACL,CAAC,CAAC,CAAC;IACL,CAAC;IAED;;;;;OAKG;IACH,KAAK,CAAC,aAAa,CAAC,SAAS,GAAG,kBAAkB;QAChD,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;YACrC,MAAM,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE;gBAC5B,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC;gBACpB,MAAM,CAAC,IAAI,oBAAoB,EAAE,CAAC,CAAC;YACrC,CAAC,EAAE,SAAS,CAAC,CAAC;YAEd,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,SAAS,EAAE,CAAC,GAAG,EAAE,GAAG,EAAE,EAAE;gBACvC,YAAY,CAAC,KAAK,CAAC,CAAC;gBACpB,MAAM,GAAG,GAAG,IAAI,GAAG,CAAC,GAAG,CAAC,GAAG,IAAI,iBAAiB,EAAE,kBAAkB,CAAC,CAAC;gBACtE,MAAM,MAAM,GAAmB;oBAC7B,IAAI,EAAE,GAAG,CAAC,YAAY,CAAC,GAAG,CAAC,MAAM,CAAC;oBAClC,KAAK,EAAE,GAAG,CAAC,YAAY,CAAC,GAAG,CAAC,OAAO,CAAC;oBACpC,KAAK,EAAE,GAAG,CAAC,YAAY,CAAC,GAAG,CAAC,OAAO,CAAC;iBACrC,CAAC;gBACF,GAAG,CAAC,SAAS,CAAC,GAAG,EAAE;oBACjB,cAAc,EAAE,0BAA0B;oBAC1C,UAAU,EAAE,OAAO;iBACpB,CAAC,CAAC;gBACH,GAAG,CAAC,GAAG,CAAC,YAAY,EAAE,GAAG,EAAE;oBACzB,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC;oBACpB,OAAO,CAAC,MAAM,CAAC,CAAC;gBAClB,CAAC,CAAC,CAAC;YACL,CAAC,CAAC,CAAC;QACL,CAAC,CAAC,CAAC;IACL,CAAC;CACF"}

package/dist/oauth/client.d.ts

@@ -0,0 +1,57 @@
+/**
+ * HTTP client for `auth.cognitum.one`'s OAuth surface (ADR-306): authorize
+ * URL construction, `POST /oauth/token` (`authorization_code` and
+ * `refresh_token` grants), and `POST /v1/oauth/code-exchange` (OOB fallback).
+ *
+ * A TypeScript port of meta-proxy's `src/oauth/client.rs`
+ * (cognitum-one/meta-proxy) — same base URL, same endpoints, same
+ * form/query parameter names, confirmed live 2026-07-16 (a real
+ * `GET /oauth/authorize?...&client_id=meta-proxy&redirect_uri=<ruflo-controlled
+ * loopback>` returns a working consent page, not a redirect_uri-mismatch
+ * error — so this client reuses meta-proxy's registered `client_id` rather
+ * than requiring a new one).
+ *
+ * Deliberately NOT `api.cognitum.one/v1/auth/*` — that's what ruflo's own
+ * checked-in OpenAPI spec (v3/docs/api/cognitum-v1.openapi.yaml, ADR-308)
+ * describes, but it does not match what the real identity server serves.
+ * This client targets the proven, live surface instead.
+ *
+ * @module v3/security/oauth/client
+ */
+export declare const CLIENT_ID = "meta-proxy";
+export declare const SCOPE = "inference";
+/** RFC 8252 out-of-band sentinel — the OOB/manual-paste flow's `redirect_uri`. */
+export declare const OOB_REDIRECT_URI = "urn:ietf:wg:oauth:2.0:oob";
+export interface TokenResponse {
+    access_token: string;
+    token_type: string;
+    account_email?: string;
+    refresh_token?: string;
+    expires_in?: number;
+}
+export declare class OAuthError extends Error {
+    readonly code: 'network' | 'protocol' | 'unexpected_shape';
+    readonly oauthError?: string | undefined;
+    readonly oauthDescription?: string | undefined;
+    constructor(message: string, code: 'network' | 'protocol' | 'unexpected_shape', oauthError?: string | undefined, oauthDescription?: string | undefined);
+}
+/** Builds the `/oauth/authorize` URL for the standard loopback-redirect flow. */
+export declare function authorizeUrl(redirectUri: string, state: string, codeChallenge: string): string;
+/** `POST /oauth/token` with `grant_type=authorization_code`. */
+export declare function exchangeCode(code: string, codeVerifier: string, redirectUri: string, base?: string): Promise<TokenResponse>;
+/**
+ * `POST /oauth/token` with `grant_type=refresh_token`. identity rotates
+ * refresh tokens with reuse detection: presenting a refresh token returns a
+ * NEW refresh token and revokes the old one, and re-presenting a spent one
+ * revokes the whole session family. Callers MUST persist the returned
+ * `refresh_token` atomically before using the new access token, and must
+ * never retry a failed refresh with the same token.
+ */
+export declare function refreshToken(refreshTokenValue: string, base?: string): Promise<TokenResponse>;
+/**
+ * `POST /v1/oauth/code-exchange` — the OOB manual-entry fallback for
+ * headless/SSH/container environments where no browser round-trip to
+ * `127.0.0.1` is reachable.
+ */
+export declare function exchangeManualCode(code: string, codeVerifier: string, base?: string): Promise<TokenResponse>;
+//# sourceMappingURL=client.d.ts.map

package/dist/oauth/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/oauth/client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,eAAO,MAAM,SAAS,eAAe,CAAC;AACtC,eAAO,MAAM,KAAK,cAAc,CAAC;AACjC,kFAAkF;AAClF,eAAO,MAAM,gBAAgB,8BAA8B,CAAC;AAO5D,MAAM,WAAW,aAAa;IAC5B,YAAY,EAAE,MAAM,CAAC;IACrB,UAAU,EAAE,MAAM,CAAC;IACnB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAOD,qBAAa,UAAW,SAAQ,KAAK;aAGjB,IAAI,EAAE,SAAS,GAAG,UAAU,GAAG,kBAAkB;aACjD,UAAU,CAAC,EAAE,MAAM;aACnB,gBAAgB,CAAC,EAAE,MAAM;gBAHzC,OAAO,EAAE,MAAM,EACC,IAAI,EAAE,SAAS,GAAG,UAAU,GAAG,kBAAkB,EACjD,UAAU,CAAC,EAAE,MAAM,YAAA,EACnB,gBAAgB,CAAC,EAAE,MAAM,YAAA;CAK5C;AAED,iFAAiF;AACjF,wBAAgB,YAAY,CAAC,WAAW,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,GAAG,MAAM,CAU9F;AAsCD,gEAAgE;AAChE,wBAAsB,YAAY,CAChC,IAAI,EAAE,MAAM,EACZ,YAAY,EAAE,MAAM,EACpB,WAAW,EAAE,MAAM,EACnB,IAAI,SAAgB,GACnB,OAAO,CAAC,aAAa,CAAC,CAMxB;AAED;;;;;;;GAOG;AACH,wBAAsB,YAAY,CAAC,iBAAiB,EAAE,MAAM,EAAE,IAAI,SAAgB,GAAG,OAAO,CAAC,aAAa,CAAC,CAE1G;AAED;;;;GAIG;AACH,wBAAsB,kBAAkB,CACtC,IAAI,EAAE,MAAM,EACZ,YAAY,EAAE,MAAM,EACpB,IAAI,SAAgB,GACnB,OAAO,CAAC,aAAa,CAAC,CAYxB"}

package/dist/oauth/client.js

@@ -0,0 +1,120 @@
+/**
+ * HTTP client for `auth.cognitum.one`'s OAuth surface (ADR-306): authorize
+ * URL construction, `POST /oauth/token` (`authorization_code` and
+ * `refresh_token` grants), and `POST /v1/oauth/code-exchange` (OOB fallback).
+ *
+ * A TypeScript port of meta-proxy's `src/oauth/client.rs`
+ * (cognitum-one/meta-proxy) — same base URL, same endpoints, same
+ * form/query parameter names, confirmed live 2026-07-16 (a real
+ * `GET /oauth/authorize?...&client_id=meta-proxy&redirect_uri=<ruflo-controlled
+ * loopback>` returns a working consent page, not a redirect_uri-mismatch
+ * error — so this client reuses meta-proxy's registered `client_id` rather
+ * than requiring a new one).
+ *
+ * Deliberately NOT `api.cognitum.one/v1/auth/*` — that's what ruflo's own
+ * checked-in OpenAPI spec (v3/docs/api/cognitum-v1.openapi.yaml, ADR-308)
+ * describes, but it does not match what the real identity server serves.
+ * This client targets the proven, live surface instead.
+ *
+ * @module v3/security/oauth/client
+ */
+export const CLIENT_ID = 'meta-proxy';
+export const SCOPE = 'inference';
+/** RFC 8252 out-of-band sentinel — the OOB/manual-paste flow's `redirect_uri`. */
+export const OOB_REDIRECT_URI = 'urn:ietf:wg:oauth:2.0:oob';
+function authBaseUrl() {
+    const override = process.env.COGNITUM_AUTH_URL;
+    return override && override.trim() ? override : 'https://auth.cognitum.one';
+}
+export class OAuthError extends Error {
+    code;
+    oauthError;
+    oauthDescription;
+    constructor(message, code, oauthError, oauthDescription) {
+        super(message);
+        this.code = code;
+        this.oauthError = oauthError;
+        this.oauthDescription = oauthDescription;
+        this.name = 'OAuthError';
+    }
+}
+/** Builds the `/oauth/authorize` URL for the standard loopback-redirect flow. */
+export function authorizeUrl(redirectUri, state, codeChallenge) {
+    const url = new URL(`${authBaseUrl()}/oauth/authorize`);
+    url.searchParams.set('response_type', 'code');
+    url.searchParams.set('client_id', CLIENT_ID);
+    url.searchParams.set('redirect_uri', redirectUri);
+    url.searchParams.set('scope', SCOPE);
+    url.searchParams.set('state', state);
+    url.searchParams.set('code_challenge', codeChallenge);
+    url.searchParams.set('code_challenge_method', 'S256');
+    return url.toString();
+}
+async function parseTokenResponse(resp) {
+    if (resp.ok) {
+        try {
+            return (await resp.json());
+        }
+        catch {
+            throw new OAuthError('unexpected response shape from the server', 'unexpected_shape');
+        }
+    }
+    try {
+        const body = (await resp.json());
+        throw new OAuthError(`oauth error: ${body.error} — ${body.error_description}`, 'protocol', body.error, body.error_description);
+    }
+    catch (e) {
+        if (e instanceof OAuthError)
+            throw e;
+        throw new OAuthError('unexpected response shape from the server', 'unexpected_shape');
+    }
+}
+async function postForm(path, form, base = authBaseUrl()) {
+    let resp;
+    try {
+        resp = await fetch(`${base}${path}`, {
+            method: 'POST',
+            headers: { 'content-type': 'application/x-www-form-urlencoded' },
+            body: new URLSearchParams(form).toString(),
+        });
+    }
+    catch (e) {
+        throw new OAuthError(`network error: ${e instanceof Error ? e.message : String(e)}`, 'network');
+    }
+    return parseTokenResponse(resp);
+}
+/** `POST /oauth/token` with `grant_type=authorization_code`. */
+export async function exchangeCode(code, codeVerifier, redirectUri, base = authBaseUrl()) {
+    return postForm('/oauth/token', { grant_type: 'authorization_code', code, code_verifier: codeVerifier, client_id: CLIENT_ID, redirect_uri: redirectUri }, base);
+}
+/**
+ * `POST /oauth/token` with `grant_type=refresh_token`. identity rotates
+ * refresh tokens with reuse detection: presenting a refresh token returns a
+ * NEW refresh token and revokes the old one, and re-presenting a spent one
+ * revokes the whole session family. Callers MUST persist the returned
+ * `refresh_token` atomically before using the new access token, and must
+ * never retry a failed refresh with the same token.
+ */
+export async function refreshToken(refreshTokenValue, base = authBaseUrl()) {
+    return postForm('/oauth/token', { grant_type: 'refresh_token', refresh_token: refreshTokenValue, client_id: CLIENT_ID }, base);
+}
+/**
+ * `POST /v1/oauth/code-exchange` — the OOB manual-entry fallback for
+ * headless/SSH/container environments where no browser round-trip to
+ * `127.0.0.1` is reachable.
+ */
+export async function exchangeManualCode(code, codeVerifier, base = authBaseUrl()) {
+    let resp;
+    try {
+        resp = await fetch(`${base}/v1/oauth/code-exchange`, {
+            method: 'POST',
+            headers: { 'content-type': 'application/json' },
+            body: JSON.stringify({ code, code_verifier: codeVerifier, client_id: CLIENT_ID }),
+        });
+    }
+    catch (e) {
+        throw new OAuthError(`network error: ${e instanceof Error ? e.message : String(e)}`, 'network');
+    }
+    return parseTokenResponse(resp);
+}
+//# sourceMappingURL=client.js.map

package/dist/oauth/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../../src/oauth/client.ts"],"names":[],"mappings":"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"}

package/dist/oauth/pkce.d.ts

@@ -0,0 +1,25 @@
+/**
+ * OAuth 2.0 + PKCE (RFC 7636) client-side generation (ADR-306).
+ *
+ * A TypeScript port of meta-proxy's `src/oauth/pkce.rs` (cognitum-one/meta-proxy,
+ * itself ported from `dashboard/apps/cli/src/pkce.rs`) so a verifier generated
+ * here validates against the same `services/identity` authorization server
+ * meta-proxy already talks to successfully — same byte lengths, same encoding,
+ * same hash. Intentionally duplicated rather than imported from
+ * `@claude-flow/mcp/src/oauth.ts` (a different, unrelated OAuth client in this
+ * monorepo) — ADR-306 assigns PKCE ownership to this package specifically.
+ *
+ * @module v3/security/oauth/pkce
+ */
+export interface PkceRequest {
+    state: string;
+    codeVerifier: string;
+    codeChallenge: string;
+}
+export declare function challengeFromVerifier(verifier: string): string;
+/**
+ * Generates a fresh `state` + PKCE verifier/challenge pair for one login
+ * attempt.
+ */
+export declare function generate(): PkceRequest;
+//# sourceMappingURL=pkce.d.ts.map

package/dist/oauth/pkce.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pkce.d.ts","sourceRoot":"","sources":["../../src/oauth/pkce.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAIH,MAAM,WAAW,WAAW;IAC1B,KAAK,EAAE,MAAM,CAAC;IACd,YAAY,EAAE,MAAM,CAAC;IACrB,aAAa,EAAE,MAAM,CAAC;CACvB;AAWD,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAE9D;AAED;;;GAGG;AACH,wBAAgB,QAAQ,IAAI,WAAW,CAKtC"}

package/dist/oauth/pkce.js

@@ -0,0 +1,36 @@
+/**
+ * OAuth 2.0 + PKCE (RFC 7636) client-side generation (ADR-306).
+ *
+ * A TypeScript port of meta-proxy's `src/oauth/pkce.rs` (cognitum-one/meta-proxy,
+ * itself ported from `dashboard/apps/cli/src/pkce.rs`) so a verifier generated
+ * here validates against the same `services/identity` authorization server
+ * meta-proxy already talks to successfully — same byte lengths, same encoding,
+ * same hash. Intentionally duplicated rather than imported from
+ * `@claude-flow/mcp/src/oauth.ts` (a different, unrelated OAuth client in this
+ * monorepo) — ADR-306 assigns PKCE ownership to this package specifically.
+ *
+ * @module v3/security/oauth/pkce
+ */
+import { randomBytes, createHash } from 'crypto';
+/**
+ * 32 random bytes, base64url-encoded (no padding) — comfortably within RFC
+ * 7636's 43-128 character verifier length requirement (32 bytes -> 43 chars).
+ * Matches the Rust port's `random_url_safe_token(32)` exactly.
+ */
+function randomUrlSafeToken(byteLen) {
+    return randomBytes(byteLen).toString('base64url');
+}
+export function challengeFromVerifier(verifier) {
+    return createHash('sha256').update(verifier).digest('base64url');
+}
+/**
+ * Generates a fresh `state` + PKCE verifier/challenge pair for one login
+ * attempt.
+ */
+export function generate() {
+    const state = randomUrlSafeToken(32);
+    const codeVerifier = randomUrlSafeToken(32);
+    const codeChallenge = challengeFromVerifier(codeVerifier);
+    return { state, codeVerifier, codeChallenge };
+}
+//# sourceMappingURL=pkce.js.map

package/dist/oauth/pkce.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pkce.js","sourceRoot":"","sources":["../../src/oauth/pkce.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,QAAQ,CAAC;AAQjD;;;;GAIG;AACH,SAAS,kBAAkB,CAAC,OAAe;IACzC,OAAO,WAAW,CAAC,OAAO,CAAC,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAC;AACpD,CAAC;AAED,MAAM,UAAU,qBAAqB,CAAC,QAAgB;IACpD,OAAO,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC;AACnE,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,QAAQ;IACtB,MAAM,KAAK,GAAG,kBAAkB,CAAC,EAAE,CAAC,CAAC;IACrC,MAAM,YAAY,GAAG,kBAAkB,CAAC,EAAE,CAAC,CAAC;IAC5C,MAAM,aAAa,GAAG,qBAAqB,CAAC,YAAY,CAAC,CAAC;IAC1D,OAAO,EAAE,KAAK,EAAE,YAAY,EAAE,aAAa,EAAE,CAAC;AAChD,CAAC"}

package/dist/path-validator.d.ts

@@ -13,6 +13,11 @@
  * - Symlink resolution (optional)
  * - Traversal pattern detection
  *
+ * Canonicalization is symmetric: a candidate is only ever compared against
+ * prefixes held in the same form it was resolved in. Canonicalizing one side
+ * and not the other silently denies everything under a symlinked prefix
+ * (async) or silently accepts an escape through one (sync).
+ *
  * @module v3/security/path-validator
  */
 export interface PathValidatorConfig {
@@ -84,7 +89,25 @@ export declare class PathValidatorError extends Error {
  */
 export declare class PathValidator {
     private readonly config;
+    /** Lexically resolved prefixes — compared against lexically resolved candidates. */
     private readonly resolvedPrefixes;
+    /**
+     * Symlink-resolved prefixes — compared against symlink-resolved candidates.
+     *
+     * Kept as a SECOND list rather than replacing `resolvedPrefixes`, because
+     * the two comparison sites derive their candidate differently: `validate()`
+     * canonicalizes through the filesystem, `validateSync()`/`isWithinAllowed()`
+     * are documented as lexical-only. Canonicalizing one side without the other
+     * is exactly the bug this fixes, in whichever direction it is done.
+     *
+     * Resolved once, at construction — so an allowed prefix denotes the
+     * directory it named when the validator was configured, and retargeting a
+     * symlink afterwards cannot silently redirect the allowlist. Re-resolving on
+     * every call would hand that control to whoever can write the link, and cost
+     * a syscall per validation. Callers needing to follow a moved target should
+     * construct a new validator.
+     */
+    private readonly canonicalPrefixes;
     constructor(config: PathValidatorConfig);
     /**
      * Validates a path against security rules.

package/dist/path-validator.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"path-validator.d.ts","sourceRoot":"","sources":["../src/path-validator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAKH,MAAM,WAAW,mBAAmB;IAClC;;;OAGG;IACH,eAAe,EAAE,MAAM,EAAE,CAAC;IAE1B;;;OAGG;IACH,iBAAiB,CAAC,EAAE,MAAM,EAAE,CAAC;IAE7B;;;OAGG;IACH,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IAExB;;;OAGG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IAEvB;;;OAGG;IACH,eAAe,CAAC,EAAE,OAAO,CAAC;IAE1B;;;OAGG;IACH,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAE3B;;;OAGG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB;AAED,MAAM,WAAW,oBAAoB;IACnC,OAAO,EAAE,OAAO,CAAC;IACjB,YAAY,EAAE,MAAM,CAAC;IACrB,YAAY,EAAE,MAAM,CAAC;IACrB,aAAa,EAAE,MAAM,CAAC;IACtB,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB;AAED,qBAAa,kBAAmB,SAAQ,KAAK;aAGzB,IAAI,EAAE,MAAM;aACZ,IAAI,CAAC,EAAE,MAAM;gBAF7B,OAAO,EAAE,MAAM,EACC,IAAI,EAAE,MAAM,EACZ,IAAI,CAAC,EAAE,MAAM,YAAA;CAKhC;AAqDD;;;;;;;;;;;;;;;;;GAiBG;AACH,qBAAa,aAAa;IACxB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAgC;IACvD,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAW;gBAEhC,MAAM,EAAE,mBAAmB;IAwBvC;;;;;OAKG;IACG,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,oBAAoB,CAAC;IAwIhE;;;;;;OAMG;IACG,eAAe,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAczD;;;;;OAKG;IACH,YAAY,CAAC,SAAS,EAAE,MAAM,GAAG,oBAAoB;IA4FrD;;;;;;OAMG;IACG,UAAU,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,QAAQ,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC;IAQxE;;;;OAIG;IACH,SAAS,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;IAQ/B;;OAEG;IACH,kBAAkB,IAAI,SAAS,MAAM,EAAE;IAIvC;;OAEG;IACH,eAAe,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO;CAU5C;AAED;;;;;GAKG;AACH,wBAAgB,0BAA0B,CAAC,WAAW,EAAE,MAAM,GAAG,aAAa,CAS7E;AAED;;;;;GAKG;AACH,wBAAgB,8BAA8B,CAAC,WAAW,EAAE,MAAM,GAAG,aAAa,CASjF"}
+{"version":3,"file":"path-validator.d.ts","sourceRoot":"","sources":["../src/path-validator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAMH,MAAM,WAAW,mBAAmB;IAClC;;;OAGG;IACH,eAAe,EAAE,MAAM,EAAE,CAAC;IAE1B;;;OAGG;IACH,iBAAiB,CAAC,EAAE,MAAM,EAAE,CAAC;IAE7B;;;OAGG;IACH,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IAExB;;;OAGG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IAEvB;;;OAGG;IACH,eAAe,CAAC,EAAE,OAAO,CAAC;IAE1B;;;OAGG;IACH,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAE3B;;;OAGG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB;AAED,MAAM,WAAW,oBAAoB;IACnC,OAAO,EAAE,OAAO,CAAC;IACjB,YAAY,EAAE,MAAM,CAAC;IACrB,YAAY,EAAE,MAAM,CAAC;IACrB,aAAa,EAAE,MAAM,CAAC;IACtB,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB;AAED,qBAAa,kBAAmB,SAAQ,KAAK;aAGzB,IAAI,EAAE,MAAM;aACZ,IAAI,CAAC,EAAE,MAAM;gBAF7B,OAAO,EAAE,MAAM,EACC,IAAI,EAAE,MAAM,EACZ,IAAI,CAAC,EAAE,MAAM,YAAA;CAKhC;AA2HD;;;;;;;;;;;;;;;;;GAiBG;AACH,qBAAa,aAAa;IACxB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAgC;IACvD,oFAAoF;IACpF,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAW;IAC5C;;;;;;;;;;;;;;;OAeG;IACH,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAW;gBAEjC,MAAM,EAAE,mBAAmB;IAqCvC;;;;;OAKG;IACG,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,oBAAoB,CAAC;IA+JhE;;;;;;OAMG;IACG,eAAe,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAczD;;;;;OAKG;IACH,YAAY,CAAC,SAAS,EAAE,MAAM,GAAG,oBAAoB;IA4FrD;;;;;;OAMG;IACG,UAAU,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,QAAQ,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC;IAQxE;;;;OAIG;IACH,SAAS,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;IAW/B;;OAEG;IACH,kBAAkB,IAAI,SAAS,MAAM,EAAE;IAIvC;;OAEG;IACH,eAAe,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO;CAU5C;AAED;;;;;GAKG;AACH,wBAAgB,0BAA0B,CAAC,WAAW,EAAE,MAAM,GAAG,aAAa,CAS7E;AAED;;;;;GAKG;AACH,wBAAgB,8BAA8B,CAAC,WAAW,EAAE,MAAM,GAAG,aAAa,CASjF"}

package/dist/path-validator.js

@@ -13,10 +13,16 @@
  * - Symlink resolution (optional)
  * - Traversal pattern detection
  *
+ * Canonicalization is symmetric: a candidate is only ever compared against
+ * prefixes held in the same form it was resolved in. Canonicalizing one side
+ * and not the other silently denies everything under a symlinked prefix
+ * (async) or silently accepts an escape through one (sync).
+ *
  * @module v3/security/path-validator
  */
 import * as path from 'path';
 import * as fs from 'fs/promises';
+import { realpathSync } from 'fs';
 export class PathValidatorError extends Error {
     code;
     path;
@@ -75,6 +81,71 @@ const DEFAULT_BLOCKED_NAMES = [
     '.npmrc',
     '.docker',
 ];
+/**
+ * Canonicalizes a path that may not exist yet, by resolving the longest
+ * ancestor that DOES exist and re-attaching the remaining segments.
+ *
+ * Plain `realpath` throws ENOENT for a path whose leaf is missing, which
+ * would leave the caller comparing a canonical prefix against a merely
+ * lexical candidate — the asymmetry this whole helper exists to avoid.
+ * Walking up also means a symlinked PARENT is still resolved, so a
+ * not-yet-created file under a symlinked directory canonicalizes to its
+ * real location instead of its lexical one.
+ *
+ * Falls back to the lexical path if the ancestor walk itself fails (EACCES,
+ * ELOOP, …), preserving the previous behaviour rather than throwing out of
+ * a validation call.
+ */
+async function canonicalize(resolvedPath) {
+    try {
+        return await fs.realpath(resolvedPath);
+    }
+    catch (error) {
+        if (error?.code !== 'ENOENT') {
+            return resolvedPath;
+        }
+    }
+    const parent = path.dirname(resolvedPath);
+    // dirname() of a root ('/' or 'C:\\') is itself — stop instead of recursing.
+    if (parent === resolvedPath) {
+        return resolvedPath;
+    }
+    return path.join(await canonicalize(parent), path.basename(resolvedPath));
+}
+/**
+ * Synchronous twin of {@link canonicalize}, for the constructor and
+ * {@link PathValidator.addPrefix} which cannot await.
+ */
+function canonicalizeSync(resolvedPath) {
+    try {
+        return realpathSync(resolvedPath);
+    }
+    catch (error) {
+        if (error?.code !== 'ENOENT') {
+            return resolvedPath;
+        }
+    }
+    const parent = path.dirname(resolvedPath);
+    if (parent === resolvedPath) {
+        return resolvedPath;
+    }
+    return path.join(canonicalizeSync(parent), path.basename(resolvedPath));
+}
+/**
+ * True if `resolvedPath` is the prefix itself or sits underneath it.
+ *
+ * The separator has to be appended to anchor the match at a path boundary, so
+ * `/srv/app-secrets` does not count as inside `/srv/app` — but a root prefix
+ * (`/`, `C:\`, a UNC share root) already ends in one, and appending a second
+ * looked for `//`, which rejected every descendant of a root prefix.
+ */
+function isWithinPrefix(resolvedPath, prefix) {
+    if (resolvedPath === prefix) {
+        return true;
+    }
+    const boundary = prefix.endsWith(path.sep) ? prefix : prefix + path.sep;
+    return resolvedPath.startsWith(boundary);
+}
 /**
  * Path validator that prevents traversal attacks.
  *
@@ -95,7 +166,25 @@ const DEFAULT_BLOCKED_NAMES = [
  */
 export class PathValidator {
     config;
+    /** Lexically resolved prefixes — compared against lexically resolved candidates. */
     resolvedPrefixes;
+    /**
+     * Symlink-resolved prefixes — compared against symlink-resolved candidates.
+     *
+     * Kept as a SECOND list rather than replacing `resolvedPrefixes`, because
+     * the two comparison sites derive their candidate differently: `validate()`
+     * canonicalizes through the filesystem, `validateSync()`/`isWithinAllowed()`
+     * are documented as lexical-only. Canonicalizing one side without the other
+     * is exactly the bug this fixes, in whichever direction it is done.
+     *
+     * Resolved once, at construction — so an allowed prefix denotes the
+     * directory it named when the validator was configured, and retargeting a
+     * symlink afterwards cannot silently redirect the allowlist. Re-resolving on
+     * every call would hand that control to whoever can write the link, and cost
+     * a syscall per validation. Callers needing to follow a moved target should
+     * construct a new validator.
+     */
+    canonicalPrefixes;
     constructor(config) {
         this.config = {
             allowedPrefixes: config.allowedPrefixes,
@@ -109,8 +198,19 @@ export class PathValidator {
         if (this.config.allowedPrefixes.length === 0) {
             throw new PathValidatorError('At least one allowed prefix must be specified', 'EMPTY_PREFIXES');
         }
-        // Pre-resolve all prefixes
+        // Pre-resolve all prefixes, lexically and canonically. #3010 — validate()
+        // canonicalizes the *candidate* through fs.realpath (when resolveSymlinks
+        // is on, the default) but prefixes were only ever path.resolve()d, never
+        // realpath'd. On any platform where the prefix itself is reached through a
+        // symlink (e.g. macOS os.tmpdir() -> /var/folders/... while /var is itself
+        // a symlink to /private/var), the realpath'd candidate can never match the
+        // non-realpath'd prefix, and every path under that prefix is rejected as
+        // "outside allowed directories" — including the prefix's own contents.
         this.resolvedPrefixes = this.config.allowedPrefixes.map(p => path.resolve(p));
+        // Always a distinct array — `addPrefix` appends to both, so aliasing the
+        // lexical list would push twice. With resolveSymlinks off no candidate is
+        // ever canonicalized and nothing reads this list, so skip the syscall.
+        this.canonicalPrefixes = this.resolvedPrefixes.map(p => this.config.resolveSymlinks ? canonicalizeSync(p) : p);
     }
     /**
      * Validates a path against security rules.
@@ -154,12 +254,17 @@ export class PathValidator {
         }
         // Resolve the path
         let resolvedPath;
+        // Which prefix list this candidate may legitimately be compared against:
+        // only a symlink-resolved candidate may be matched against symlink-resolved
+        // prefixes. See `canonicalPrefixes`.
+        let symlinksResolved = false;
         try {
             resolvedPath = path.resolve(inputPath);
             // Optionally resolve symlinks
             if (this.config.resolveSymlinks) {
                 try {
                     resolvedPath = await fs.realpath(resolvedPath);
+                    symlinksResolved = true;
                 }
                 catch (error) {
                     // Path doesn't exist yet - use resolved path
@@ -171,6 +276,20 @@ export class PathValidator {
                             errors.push(`Failed to resolve path: ${error.message}`);
                         }
                     }
+                    if (error.code === 'ENOENT' && this.config.allowNonExistent) {
+                        // The leaf does not exist, but its ancestors may still be
+                        // symlinks. Canonicalize what exists so the candidate is in the
+                        // same form as `canonicalPrefixes` — otherwise every not-yet-
+                        // created path under a symlinked prefix (macOS `/var` ->
+                        // `/private/var`, `/tmp` -> `/private/tmp`) fails to match.
+                        //
+                        // Only when non-existent paths are actually allowed: with
+                        // `allowNonExistent: false` this call is already a failure, and
+                        // canonicalizing anyway would change the `resolvedPath` and
+                        // `matchedPrefix` reported to callers for no benefit.
+                        resolvedPath = await canonicalize(resolvedPath);
+                        symlinksResolved = true;
+                    }
                 }
             }
         }
@@ -187,8 +306,11 @@ export class PathValidator {
         let matchedPrefix = '';
         let relativePath = '';
         let prefixMatched = false;
-        for (const prefix of this.resolvedPrefixes) {
-            if (resolvedPath === prefix || resolvedPath.startsWith(prefix + path.sep)) {
+        const prefixes = symlinksResolved
+            ? this.canonicalPrefixes
+            : this.resolvedPrefixes;
+        for (const prefix of prefixes) {
+            if (isWithinPrefix(resolvedPath, prefix)) {
                 prefixMatched = true;
                 matchedPrefix = prefix;
                 relativePath = resolvedPath.slice(prefix.length);
@@ -299,7 +421,7 @@ export class PathValidator {
         let relativePath = '';
         let prefixMatched = false;
         for (const prefix of this.resolvedPrefixes) {
-            if (resolvedPath === prefix || resolvedPath.startsWith(prefix + path.sep)) {
+            if (isWithinPrefix(resolvedPath, prefix)) {
                 prefixMatched = true;
                 matchedPrefix = prefix;
                 relativePath = resolvedPath.slice(prefix.length);
@@ -366,6 +488,7 @@ export class PathValidator {
         if (!this.resolvedPrefixes.includes(resolved)) {
             this.config.allowedPrefixes.push(prefix);
             this.resolvedPrefixes.push(resolved);
+            this.canonicalPrefixes.push(this.config.resolveSymlinks ? canonicalizeSync(resolved) : resolved);
         }
     }
     /**
@@ -380,7 +503,7 @@ export class PathValidator {
     isWithinAllowed(inputPath) {
         try {
             const resolved = path.resolve(inputPath);
-            return this.resolvedPrefixes.some(prefix => resolved === prefix || resolved.startsWith(prefix + path.sep));
+            return this.resolvedPrefixes.some(prefix => isWithinPrefix(resolved, prefix));
         }
         catch {
             return false;