@canon-protocol/sdk 8.0.1 → 8.1.0

package/dist/auth/AuthenticatedFetch.d.ts

@@ -0,0 +1,11 @@
+import type { CredentialStore } from './CredentialStore.js';
+/**
+ * A fetch function that adds authentication headers for a publisher.
+ * Accepts an optional method parameter for correct DPoP proof generation.
+ */
+export type AuthenticatedFetchFn = (url: string, publisher: string, method?: string) => Promise<Response>;
+/**
+ * Create an authenticated fetch function that adds Bearer or DPoP
+ * authorization headers based on stored credentials.
+ */
+export declare function createAuthenticatedFetch(credentialStore?: CredentialStore): AuthenticatedFetchFn;

package/dist/auth/AuthenticatedFetch.js

@@ -0,0 +1,58 @@
+import { isExpired } from './CredentialBackend.js';
+import { createDPoPProof } from './DPoP.js';
+/**
+ * Create an authenticated fetch function that adds Bearer or DPoP
+ * authorization headers based on stored credentials.
+ */
+export function createAuthenticatedFetch(credentialStore) {
+    const dpopNonces = new Map();
+    return async (url, publisher, method = 'GET') => {
+        if (!credentialStore) {
+            return fetch(url, { method });
+        }
+        const credential = await credentialStore.getCredential(publisher);
+        if (!credential?.accessToken) {
+            return fetch(url, { method });
+        }
+        if (isExpired(credential)) {
+            console.warn(`  Warning: Access token for '${publisher}' is expired. Run 'canon login ${publisher}' to re-authenticate.`);
+            // Still attempt the request — the server will return 401 which is more informative than failing silently
+        }
+        const headers = {};
+        if (credential.dpopKeyPair) {
+            const nonce = dpopNonces.get(publisher);
+            try {
+                const proof = createDPoPProof(credential.dpopKeyPair.privateKey, credential.dpopKeyPair.publicKey, method, url, credential.accessToken, nonce);
+                headers['Authorization'] = `DPoP ${credential.accessToken}`;
+                headers['DPoP'] = proof;
+            }
+            catch (err) {
+                const msg = err instanceof Error ? err.message : String(err);
+                console.error(`  Error: Failed to create DPoP proof for '${publisher}': ${msg}\n` +
+                    `  The stored key pair may be corrupted. Run 'canon login ${publisher}' to re-authenticate.`);
+                // Fall back to Bearer as a best effort
+                headers['Authorization'] = `Bearer ${credential.accessToken}`;
+            }
+        }
+        else {
+            headers['Authorization'] = `Bearer ${credential.accessToken}`;
+        }
+        let response = await fetch(url, { method, headers });
+        // Handle DPoP nonce requirement (RFC 9449 Section 7.1)
+        if (response.status === 401 && credential.dpopKeyPair) {
+            const newNonce = response.headers.get('DPoP-Nonce');
+            if (newNonce) {
+                dpopNonces.set(publisher, newNonce);
+                try {
+                    const retryProof = createDPoPProof(credential.dpopKeyPair.privateKey, credential.dpopKeyPair.publicKey, method, url, credential.accessToken, newNonce);
+                    headers['DPoP'] = retryProof;
+                    response = await fetch(url, { method, headers });
+                }
+                catch {
+                    // DPoP retry failed — return the original 401
+                }
+            }
+        }
+        return response;
+    };
+}

package/dist/auth/CredentialBackend.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Pluggable credential storage backend interface.
+ * Implementations store OAuth credentials per publisher domain
+ * in platform-specific secure stores.
+ */
+export interface CredentialBackend {
+    get(publisher: string): Promise<StoredCredential | null>;
+    store(publisher: string, credential: StoredCredential): Promise<void>;
+    remove(publisher: string): Promise<void>;
+    list(): Promise<string[]>;
+}
+/**
+ * OAuth credential stored per publisher host.
+ * Matches the OAuthCredentialStore types from @canon-protocol/types.
+ */
+export interface StoredCredential {
+    clientId?: string | null;
+    clientSecret?: string | null;
+    accessToken?: string | null;
+    refreshToken?: string | null;
+    expiresAt?: string | null;
+    tokenEndpoint?: string | null;
+    dpopKeyPair?: DPoPKeyPair | null;
+}
+export interface DPoPKeyPair {
+    publicKey: Record<string, unknown>;
+    privateKey: Record<string, unknown>;
+}
+export declare function isExpired(credential: StoredCredential): boolean;
+export declare function hasValidToken(credential: StoredCredential): boolean;
+export declare function normalizeHost(host: string): string;

package/dist/auth/CredentialBackend.js

@@ -0,0 +1,21 @@
+export function isExpired(credential) {
+    if (!credential.expiresAt)
+        return false;
+    const expiresAt = new Date(credential.expiresAt);
+    const bufferMs = 5 * 60 * 1000; // 5 minute buffer
+    return expiresAt.getTime() <= Date.now() + bufferMs;
+}
+export function hasValidToken(credential) {
+    return !!credential.accessToken && !isExpired(credential);
+}
+export function normalizeHost(host) {
+    const normalized = host
+        .replace(/^https?:\/\//, '')
+        .replace(/^git:\/\//, '')
+        .replace(/\/+$/, '')
+        .trim();
+    if (!normalized) {
+        throw new Error('Publisher host cannot be empty');
+    }
+    return normalized;
+}

package/dist/auth/CredentialHelperBackend.d.ts

@@ -0,0 +1,17 @@
+import type { CredentialBackend, StoredCredential } from './CredentialBackend.js';
+/**
+ * External credential helper backend.
+ * Delegates to an enterprise-configured binary using a stdin/stdout JSON protocol.
+ *
+ * Configure in ~/.canon/config.json:
+ *   { "credentialHelper": "/usr/local/bin/canon-credential-vault" }
+ */
+export declare class CredentialHelperBackend implements CredentialBackend {
+    private readonly helperPath;
+    constructor(helperPath: string);
+    get(publisher: string): Promise<StoredCredential | null>;
+    store(publisher: string, credential: StoredCredential): Promise<void>;
+    remove(publisher: string): Promise<void>;
+    list(): Promise<string[]>;
+    private runHelper;
+}

package/dist/auth/CredentialHelperBackend.js

@@ -0,0 +1,93 @@
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { normalizeHost } from './CredentialBackend.js';
+const execFileAsync = promisify(execFile);
+const TIMEOUT_MS = 30_000;
+/**
+ * External credential helper backend.
+ * Delegates to an enterprise-configured binary using a stdin/stdout JSON protocol.
+ *
+ * Configure in ~/.canon/config.json:
+ *   { "credentialHelper": "/usr/local/bin/canon-credential-vault" }
+ */
+export class CredentialHelperBackend {
+    helperPath;
+    constructor(helperPath) {
+        this.helperPath = helperPath;
+    }
+    async get(publisher) {
+        const host = normalizeHost(publisher);
+        try {
+            const stdout = await this.runHelper('get', { publisher: host });
+            const trimmed = stdout.trim();
+            if (!trimmed)
+                return null;
+            return JSON.parse(trimmed);
+        }
+        catch (err) {
+            throw new Error(`Credential helper '${this.helperPath}' failed to read credential for '${host}': ${errorMsg(err)}\n` +
+                `  Verify the helper binary exists, is executable, and implements the Canon credential helper protocol.\n` +
+                `  Check the 'credentialHelper' path in ~/.canon/config.json.`);
+        }
+    }
+    async store(publisher, credential) {
+        const host = normalizeHost(publisher);
+        try {
+            await this.runHelper('store', { publisher: host, credential });
+        }
+        catch (err) {
+            throw new Error(`Credential helper '${this.helperPath}' failed to store credential for '${host}': ${errorMsg(err)}\n` +
+                `  Verify the helper binary supports the 'store' action.`);
+        }
+    }
+    async remove(publisher) {
+        const host = normalizeHost(publisher);
+        try {
+            await this.runHelper('erase', { publisher: host });
+        }
+        catch (err) {
+            console.warn(`  Warning: Credential helper '${this.helperPath}' failed to erase credential for '${host}': ${errorMsg(err)}`);
+        }
+    }
+    async list() {
+        try {
+            const stdout = await this.runHelper('list', undefined);
+            return JSON.parse(stdout.trim());
+        }
+        catch (err) {
+            console.warn(`  Warning: Credential helper '${this.helperPath}' failed to list credentials: ${errorMsg(err)}`);
+            return [];
+        }
+    }
+    async runHelper(action, input) {
+        try {
+            const { stdout } = await execFileAsync(this.helperPath, [action], {
+                ...(input && { input: JSON.stringify(input) }),
+                timeout: TIMEOUT_MS,
+            });
+            return stdout;
+        }
+        catch (err) {
+            if (isEnoent(err)) {
+                throw new Error(`Credential helper not found at '${this.helperPath}'.\n` +
+                    `  Check the 'credentialHelper' path in ~/.canon/config.json.`);
+            }
+            if (isTimeout(err)) {
+                throw new Error(`Credential helper '${this.helperPath}' timed out after ${TIMEOUT_MS / 1000}s on '${action}'.\n` +
+                    `  The helper may be waiting for authentication to an external vault.`);
+            }
+            throw err;
+        }
+    }
+}
+function errorMsg(err) {
+    if (err instanceof Error)
+        return err.message;
+    return String(err);
+}
+function isEnoent(err) {
+    return err instanceof Error && 'code' in err && err.code === 'ENOENT';
+}
+function isTimeout(err) {
+    return err instanceof Error && 'killed' in err && err.killed;
+}

package/dist/auth/CredentialStore.d.ts

@@ -0,0 +1,29 @@
+import type { CredentialBackend, StoredCredential } from './CredentialBackend.js';
+/**
+ * Credential store orchestrator.
+ * Selects the appropriate backend based on platform and configuration.
+ *
+ * Resolution order:
+ *   1. CANON_TOKEN_{PUBLISHER} environment variable (CI/CD)
+ *   2. Credential helper binary (enterprise vaults)
+ *   3. OS credential store (macOS Keychain / Windows CredMan / Linux Secret Service)
+ *   4. Encrypted file fallback (headless Linux / containers)
+ */
+export declare class CredentialStore {
+    private backend;
+    private backendReady;
+    getBackend(): Promise<CredentialBackend>;
+    /**
+     * Get an access token for a publisher.
+     * Checks env vars first, then the credential backend.
+     */
+    getToken(publisher: string): Promise<string | null>;
+    /**
+     * Get the full stored credential (including DPoP key pair).
+     */
+    getCredential(publisher: string): Promise<StoredCredential | null>;
+    store(publisher: string, credential: StoredCredential): Promise<void>;
+    remove(publisher: string): Promise<void>;
+    list(): Promise<string[]>;
+    private resolveBackend;
+}

package/dist/auth/CredentialStore.js

@@ -0,0 +1,122 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { normalizeHost, hasValidToken } from './CredentialBackend.js';
+import { KeychainBackend } from './KeychainBackend.js';
+import { WinCredBackend } from './WinCredBackend.js';
+import { SecretServiceBackend, hasSecretTool } from './SecretServiceBackend.js';
+import { EncryptedFileBackend } from './EncryptedFileBackend.js';
+import { CredentialHelperBackend } from './CredentialHelperBackend.js';
+const CONFIG_FILE = join(homedir(), '.canon', 'config.json');
+/**
+ * Credential store orchestrator.
+ * Selects the appropriate backend based on platform and configuration.
+ *
+ * Resolution order:
+ *   1. CANON_TOKEN_{PUBLISHER} environment variable (CI/CD)
+ *   2. Credential helper binary (enterprise vaults)
+ *   3. OS credential store (macOS Keychain / Windows CredMan / Linux Secret Service)
+ *   4. Encrypted file fallback (headless Linux / containers)
+ */
+export class CredentialStore {
+    backend = null;
+    backendReady = null;
+    async getBackend() {
+        if (this.backend)
+            return this.backend;
+        if (this.backendReady)
+            return this.backendReady;
+        this.backendReady = this.resolveBackend();
+        try {
+            this.backend = await this.backendReady;
+            return this.backend;
+        }
+        catch (err) {
+            // Reset so next call retries instead of returning the rejected promise
+            this.backendReady = null;
+            throw err;
+        }
+    }
+    /**
+     * Get an access token for a publisher.
+     * Checks env vars first, then the credential backend.
+     */
+    async getToken(publisher) {
+        // 1. Environment variable override
+        const envToken = getEnvToken(publisher);
+        if (envToken)
+            return envToken;
+        // 2. Credential backend
+        const backend = await this.getBackend();
+        const credential = await backend.get(publisher);
+        if (!credential)
+            return null;
+        if (!hasValidToken(credential))
+            return null;
+        return credential.accessToken ?? null;
+    }
+    /**
+     * Get the full stored credential (including DPoP key pair).
+     */
+    async getCredential(publisher) {
+        const backend = await this.getBackend();
+        return backend.get(publisher);
+    }
+    async store(publisher, credential) {
+        const backend = await this.getBackend();
+        return backend.store(publisher, credential);
+    }
+    async remove(publisher) {
+        const backend = await this.getBackend();
+        return backend.remove(publisher);
+    }
+    async list() {
+        const backend = await this.getBackend();
+        return backend.list();
+    }
+    async resolveBackend() {
+        const config = loadConfig();
+        // 1. Credential helper (enterprise)
+        if (config.credentialHelper) {
+            return new CredentialHelperBackend(config.credentialHelper);
+        }
+        // 2. OS credential store
+        if (process.platform === 'darwin') {
+            return new KeychainBackend();
+        }
+        if (process.platform === 'win32') {
+            return new WinCredBackend();
+        }
+        // Linux: try Secret Service, fall back to encrypted file
+        if (await hasSecretTool()) {
+            return new SecretServiceBackend();
+        }
+        // 3. Encrypted file fallback
+        return new EncryptedFileBackend();
+    }
+}
+/**
+ * Check for a publisher-specific environment variable token.
+ * CANON_TOKEN_{NORMALIZED_PUBLISHER} — dots/hyphens become underscores, uppercased.
+ * e.g., canon.vpn.enterprise.com → CANON_TOKEN_CANON_VPN_ENTERPRISE_COM
+ */
+function getEnvToken(publisher) {
+    const host = normalizeHost(publisher);
+    const envKey = 'CANON_TOKEN_' + host
+        .replace(/[.\-]/g, '_')
+        .toUpperCase();
+    return process.env[envKey] ?? null;
+}
+function loadConfig() {
+    if (!existsSync(CONFIG_FILE))
+        return {};
+    try {
+        return JSON.parse(readFileSync(CONFIG_FILE, 'utf-8'));
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        console.warn(`  Warning: Failed to parse ${CONFIG_FILE}: ${msg}\n` +
+            `  Using default credential backend. Fix the JSON syntax or delete the file.`);
+        return {};
+    }
+}

package/dist/auth/DPoP.d.ts

@@ -0,0 +1,28 @@
+import type { DPoPKeyPair } from './CredentialBackend.js';
+/**
+ * DPoP (Demonstrating Proof-of-Possession) implementation per RFC 9449.
+ * Binds access tokens to a cryptographic key pair so stolen tokens
+ * are unusable without the private key.
+ *
+ * All crypto uses Node.js built-in modules — no external dependencies.
+ */
+/**
+ * Generate an ephemeral EC P-256 key pair for DPoP.
+ * Returns keys in JWK format for storage in the credential store.
+ */
+export declare function generateDPoPKeyPair(): DPoPKeyPair;
+/**
+ * Create a DPoP proof JWT for an HTTP request.
+ *
+ * @param privateKeyJwk - The private key in JWK format
+ * @param publicKeyJwk - The public key in JWK format (included in JWT header)
+ * @param method - HTTP method (e.g., "GET", "POST")
+ * @param url - Target URL
+ * @param accessToken - If present, the access token hash is included (ath claim)
+ * @param nonce - Server-provided DPoP nonce (from DPoP-Nonce header)
+ */
+export declare function createDPoPProof(privateKeyJwk: Record<string, unknown>, publicKeyJwk: Record<string, unknown>, method: string, url: string, accessToken?: string, nonce?: string): string;
+/**
+ * Check if an OAuth server supports DPoP by inspecting its metadata.
+ */
+export declare function serverSupportsDPoP(dpopSigningAlgValues?: string[] | null): boolean;

package/dist/auth/DPoP.js

@@ -0,0 +1,87 @@
+import { createHash, createPrivateKey, generateKeyPairSync, randomUUID, sign } from 'node:crypto';
+/**
+ * DPoP (Demonstrating Proof-of-Possession) implementation per RFC 9449.
+ * Binds access tokens to a cryptographic key pair so stolen tokens
+ * are unusable without the private key.
+ *
+ * All crypto uses Node.js built-in modules — no external dependencies.
+ */
+/**
+ * Generate an ephemeral EC P-256 key pair for DPoP.
+ * Returns keys in JWK format for storage in the credential store.
+ */
+export function generateDPoPKeyPair() {
+    const { publicKey, privateKey } = generateKeyPairSync('ec', {
+        namedCurve: 'P-256',
+    });
+    return {
+        publicKey: publicKey.export({ format: 'jwk' }),
+        privateKey: privateKey.export({ format: 'jwk' }),
+    };
+}
+/**
+ * Create a DPoP proof JWT for an HTTP request.
+ *
+ * @param privateKeyJwk - The private key in JWK format
+ * @param publicKeyJwk - The public key in JWK format (included in JWT header)
+ * @param method - HTTP method (e.g., "GET", "POST")
+ * @param url - Target URL
+ * @param accessToken - If present, the access token hash is included (ath claim)
+ * @param nonce - Server-provided DPoP nonce (from DPoP-Nonce header)
+ */
+export function createDPoPProof(privateKeyJwk, publicKeyJwk, method, url, accessToken, nonce) {
+    const header = {
+        alg: 'ES256',
+        typ: 'dpop+jwt',
+        jwk: {
+            kty: publicKeyJwk.kty,
+            crv: publicKeyJwk.crv,
+            x: publicKeyJwk.x,
+            y: publicKeyJwk.y,
+        },
+    };
+    const payload = {
+        jti: randomUUID(),
+        htm: method.toUpperCase(),
+        htu: url,
+        iat: Math.floor(Date.now() / 1000),
+    };
+    if (accessToken) {
+        payload.ath = createHash('sha256')
+            .update(accessToken)
+            .digest('base64url');
+    }
+    if (nonce) {
+        payload.nonce = nonce;
+    }
+    return signJwt(header, payload, privateKeyJwk);
+}
+/**
+ * Check if an OAuth server supports DPoP by inspecting its metadata.
+ */
+export function serverSupportsDPoP(dpopSigningAlgValues) {
+    if (!dpopSigningAlgValues || dpopSigningAlgValues.length === 0)
+        return false;
+    return dpopSigningAlgValues.some(alg => alg.toUpperCase() === 'ES256');
+}
+/**
+ * Minimal JWT signing for ES256 (ECDSA with P-256 + SHA-256).
+ * No external JWT library needed.
+ */
+function signJwt(header, payload, privateKeyJwk) {
+    const headerB64 = base64url(JSON.stringify(header));
+    const payloadB64 = base64url(JSON.stringify(payload));
+    const signingInput = `${headerB64}.${payloadB64}`;
+    const key = createPrivateKey({ key: privateKeyJwk, format: 'jwk' });
+    // Node.js sign() returns DER-encoded ECDSA signature.
+    // JWT requires raw R||S format (64 bytes for P-256).
+    const derSignature = sign('SHA256', Buffer.from(signingInput), {
+        key,
+        dsaEncoding: 'ieee-p1363',
+    });
+    const signatureB64 = derSignature.toString('base64url');
+    return `${signingInput}.${signatureB64}`;
+}
+function base64url(str) {
+    return Buffer.from(str, 'utf-8').toString('base64url');
+}

package/dist/auth/EncryptedFileBackend.d.ts

@@ -0,0 +1,18 @@
+import type { CredentialBackend, StoredCredential } from './CredentialBackend.js';
+/**
+ * Encrypted file credential backend.
+ * Fallback for headless Linux, containers, and CI environments
+ * where no OS keyring is available.
+ *
+ * - Key: ~/.config/canon/keyring.key (random 32 bytes, mode 0600)
+ * - Secrets: ~/.config/canon/credentials.enc (AES-256-GCM encrypted JSON)
+ */
+export declare class EncryptedFileBackend implements CredentialBackend {
+    get(publisher: string): Promise<StoredCredential | null>;
+    store(publisher: string, credential: StoredCredential): Promise<void>;
+    remove(publisher: string): Promise<void>;
+    list(): Promise<string[]>;
+    private loadStore;
+    private saveStore;
+    private getOrCreateKey;
+}

package/dist/auth/EncryptedFileBackend.js

@@ -0,0 +1,94 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { createCipheriv, createDecipheriv, randomBytes } from 'node:crypto';
+import { homedir } from 'node:os';
+import { join, dirname } from 'node:path';
+import { normalizeHost } from './CredentialBackend.js';
+const CONFIG_DIR = join(homedir(), '.config', 'canon');
+const KEY_FILE = join(CONFIG_DIR, 'keyring.key');
+const SECRETS_FILE = join(CONFIG_DIR, 'credentials.enc');
+const ALGORITHM = 'aes-256-gcm';
+const KEY_LENGTH = 32;
+const IV_LENGTH = 12;
+const AUTH_TAG_LENGTH = 16;
+/**
+ * Encrypted file credential backend.
+ * Fallback for headless Linux, containers, and CI environments
+ * where no OS keyring is available.
+ *
+ * - Key: ~/.config/canon/keyring.key (random 32 bytes, mode 0600)
+ * - Secrets: ~/.config/canon/credentials.enc (AES-256-GCM encrypted JSON)
+ */
+export class EncryptedFileBackend {
+    async get(publisher) {
+        const store = this.loadStore();
+        const host = normalizeHost(publisher);
+        return store[host] ?? null;
+    }
+    async store(publisher, credential) {
+        const store = this.loadStore();
+        const host = normalizeHost(publisher);
+        store[host] = credential;
+        this.saveStore(store);
+    }
+    async remove(publisher) {
+        const store = this.loadStore();
+        const host = normalizeHost(publisher);
+        delete store[host];
+        this.saveStore(store);
+    }
+    async list() {
+        const store = this.loadStore();
+        return Object.keys(store);
+    }
+    loadStore() {
+        if (!existsSync(SECRETS_FILE))
+            return {};
+        try {
+            const key = this.getOrCreateKey();
+            const encrypted = readFileSync(SECRETS_FILE);
+            if (encrypted.length < IV_LENGTH + AUTH_TAG_LENGTH)
+                return {};
+            const iv = encrypted.subarray(0, IV_LENGTH);
+            const authTag = encrypted.subarray(IV_LENGTH, IV_LENGTH + AUTH_TAG_LENGTH);
+            const ciphertext = encrypted.subarray(IV_LENGTH + AUTH_TAG_LENGTH);
+            const decipher = createDecipheriv(ALGORITHM, key, iv);
+            decipher.setAuthTag(authTag);
+            const decrypted = Buffer.concat([
+                decipher.update(ciphertext),
+                decipher.final(),
+            ]);
+            return JSON.parse(decrypted.toString('utf-8'));
+        }
+        catch {
+            // Decryption failed — key was regenerated, file is corrupted, etc.
+            // Return empty store; next save will overwrite with valid data.
+            return {};
+        }
+    }
+    saveStore(store) {
+        const key = this.getOrCreateKey();
+        const iv = randomBytes(IV_LENGTH);
+        const cipher = createCipheriv(ALGORITHM, key, iv);
+        const plaintext = Buffer.from(JSON.stringify(store), 'utf-8');
+        const ciphertext = Buffer.concat([cipher.update(plaintext), cipher.final()]);
+        const authTag = cipher.getAuthTag();
+        // File format: [iv (12)] [authTag (16)] [ciphertext ...]
+        const output = Buffer.concat([iv, authTag, ciphertext]);
+        mkdirSync(dirname(SECRETS_FILE), { recursive: true });
+        writeFileSync(SECRETS_FILE, output, { mode: 0o600 });
+    }
+    getOrCreateKey() {
+        if (existsSync(KEY_FILE)) {
+            const key = readFileSync(KEY_FILE);
+            if (key.length !== KEY_LENGTH) {
+                throw new Error(`Credential keyring key is corrupted (expected ${KEY_LENGTH} bytes, got ${key.length}). ` +
+                    `Delete ${KEY_FILE} and re-authenticate.`);
+            }
+            return key;
+        }
+        const key = randomBytes(KEY_LENGTH);
+        mkdirSync(dirname(KEY_FILE), { recursive: true });
+        writeFileSync(KEY_FILE, key, { mode: 0o600 });
+        return key;
+    }
+}

package/dist/auth/KeychainBackend.d.ts

@@ -0,0 +1,11 @@
+import type { CredentialBackend, StoredCredential } from './CredentialBackend.js';
+/**
+ * macOS Keychain credential backend.
+ * Stores credentials via the `security` CLI tool (no native modules).
+ */
+export declare class KeychainBackend implements CredentialBackend {
+    get(publisher: string): Promise<StoredCredential | null>;
+    store(publisher: string, credential: StoredCredential): Promise<void>;
+    remove(publisher: string): Promise<void>;
+    list(): Promise<string[]>;
+}

package/dist/auth/KeychainBackend.js

@@ -0,0 +1,104 @@
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { normalizeHost } from './CredentialBackend.js';
+const execFileAsync = promisify(execFile);
+const SERVICE = 'canon';
+const SECURITY_BIN = '/usr/bin/security';
+/**
+ * macOS Keychain credential backend.
+ * Stores credentials via the `security` CLI tool (no native modules).
+ */
+export class KeychainBackend {
+    async get(publisher) {
+        const account = normalizeHost(publisher);
+        try {
+            const { stdout } = await execFileAsync(SECURITY_BIN, [
+                'find-generic-password',
+                '-s', SERVICE,
+                '-a', account,
+                '-w',
+            ], { timeout: 10_000 });
+            try {
+                return JSON.parse(stdout.trim());
+            }
+            catch {
+                throw new Error(`Stored credential for '${account}' is corrupted (not valid JSON).\n` +
+                    `  Run 'canon logout ${account}' then 'canon login ${account}' to fix.`);
+            }
+        }
+        catch (err) {
+            if (isExitCode(err, 44))
+                return null; // errSecItemNotFound
+            throw new Error(`macOS Keychain read failed for '${account}': ${errorMsg(err)}\n` +
+                `  The Keychain may be locked or inaccessible.\n` +
+                `  Try unlocking it via Keychain Access.app or running 'security unlock-keychain'.`);
+        }
+    }
+    async store(publisher, credential) {
+        const account = normalizeHost(publisher);
+        const json = JSON.stringify(credential);
+        try {
+            await execFileAsync(SECURITY_BIN, [
+                'add-generic-password',
+                '-s', SERVICE,
+                '-a', account,
+                '-U',
+                '-w', json,
+            ], { timeout: 10_000 });
+        }
+        catch (err) {
+            throw new Error(`macOS Keychain write failed for '${account}': ${errorMsg(err)}\n` +
+                `  Ensure the Keychain is unlocked and the CLI has write permission.\n` +
+                `  On managed devices, your IT policy may block credential storage.`);
+        }
+    }
+    async remove(publisher) {
+        const account = normalizeHost(publisher);
+        try {
+            await execFileAsync(SECURITY_BIN, [
+                'delete-generic-password',
+                '-s', SERVICE,
+                '-a', account,
+            ], { timeout: 10_000 });
+        }
+        catch (err) {
+            if (isExitCode(err, 44))
+                return; // already gone
+            console.warn(`  Warning: macOS Keychain delete failed for '${account}': ${errorMsg(err)}\n` +
+                `  The credential may not have been fully removed.`);
+        }
+    }
+    async list() {
+        try {
+            const { stdout } = await execFileAsync(SECURITY_BIN, [
+                'dump-keychain',
+            ], { timeout: 10_000 });
+            const accounts = [];
+            let inCanonEntry = false;
+            for (const line of stdout.split('\n')) {
+                if (line.includes(`"svce"<blob>="${SERVICE}"`)) {
+                    inCanonEntry = true;
+                }
+                if (inCanonEntry && line.includes('"acct"<blob>=')) {
+                    const match = line.match(/"acct"<blob>="([^"]+)"/);
+                    if (match)
+                        accounts.push(match[1]);
+                    inCanonEntry = false;
+                }
+            }
+            return accounts;
+        }
+        catch (err) {
+            console.warn(`  Warning: Could not enumerate Keychain entries: ${errorMsg(err)}`);
+            return [];
+        }
+    }
+}
+function isExitCode(err, code) {
+    return typeof err === 'object' && err !== null && 'code' in err && err.code === code;
+}
+function errorMsg(err) {
+    if (err instanceof Error)
+        return err.message;
+    return String(err);
+}

package/dist/auth/SecretServiceBackend.d.ts

@@ -0,0 +1,23 @@
+import type { CredentialBackend, StoredCredential } from './CredentialBackend.js';
+/**
+ * Linux Secret Service backend (GNOME Keyring / KDE Wallet).
+ * Uses the `secret-tool` CLI from libsecret-tools.
+ *
+ * Each publisher's credential is stored with attributes:
+ *   service = "canon"
+ *   publisher = normalized publisher host
+ *
+ * All interactions use execFile (no shell) to prevent command injection.
+ * The store() method uses spawn with stdin piping since secret-tool
+ * reads the secret value from stdin.
+ */
+export declare class SecretServiceBackend implements CredentialBackend {
+    get(publisher: string): Promise<StoredCredential | null>;
+    store(publisher: string, credential: StoredCredential): Promise<void>;
+    remove(publisher: string): Promise<void>;
+    list(): Promise<string[]>;
+}
+/**
+ * Check if secret-tool is available on the system.
+ */
+export declare function hasSecretTool(): Promise<boolean>;

package/dist/auth/SecretServiceBackend.js

@@ -0,0 +1,103 @@
+import { execFile, spawn } from 'node:child_process';
+import { promisify } from 'node:util';
+import { normalizeHost } from './CredentialBackend.js';
+const execFileAsync = promisify(execFile);
+const SERVICE_ATTR = 'canon';
+/**
+ * Linux Secret Service backend (GNOME Keyring / KDE Wallet).
+ * Uses the `secret-tool` CLI from libsecret-tools.
+ *
+ * Each publisher's credential is stored with attributes:
+ *   service = "canon"
+ *   publisher = normalized publisher host
+ *
+ * All interactions use execFile (no shell) to prevent command injection.
+ * The store() method uses spawn with stdin piping since secret-tool
+ * reads the secret value from stdin.
+ */
+export class SecretServiceBackend {
+    async get(publisher) {
+        const host = normalizeHost(publisher);
+        try {
+            const { stdout } = await execFileAsync('secret-tool', [
+                'lookup',
+                'service', SERVICE_ATTR,
+                'publisher', host,
+            ], { timeout: 10_000 });
+            const trimmed = stdout.trim();
+            if (!trimmed)
+                return null;
+            return JSON.parse(trimmed);
+        }
+        catch {
+            return null;
+        }
+    }
+    async store(publisher, credential) {
+        const host = normalizeHost(publisher);
+        const json = JSON.stringify(credential);
+        // Use spawn with stdin to avoid shell injection.
+        // secret-tool store reads the secret value from stdin.
+        await new Promise((resolve, reject) => {
+            const proc = spawn('secret-tool', [
+                'store',
+                '--label', `Canon: ${host}`,
+                'service', SERVICE_ATTR,
+                'publisher', host,
+            ], { stdio: ['pipe', 'ignore', 'ignore'], timeout: 10_000 });
+            proc.stdin.write(json);
+            proc.stdin.end();
+            proc.on('close', (code) => {
+                if (code === 0)
+                    resolve();
+                else
+                    reject(new Error(`secret-tool store exited with code ${code}`));
+            });
+            proc.on('error', reject);
+        });
+    }
+    async remove(publisher) {
+        const host = normalizeHost(publisher);
+        try {
+            await execFileAsync('secret-tool', [
+                'clear',
+                'service', SERVICE_ATTR,
+                'publisher', host,
+            ], { timeout: 10_000 });
+        }
+        catch {
+            // Ignore errors (credential may not exist)
+        }
+    }
+    async list() {
+        try {
+            const { stdout } = await execFileAsync('secret-tool', [
+                'search',
+                'service', SERVICE_ATTR,
+            ], { timeout: 10_000 });
+            const publishers = [];
+            for (const line of stdout.split('\n')) {
+                const match = line.match(/attribute\.publisher\s*=\s*(.+)/);
+                if (match)
+                    publishers.push(match[1].trim());
+            }
+            return publishers;
+        }
+        catch {
+            return [];
+        }
+    }
+}
+/**
+ * Check if secret-tool is available on the system.
+ */
+export async function hasSecretTool() {
+    try {
+        // 'command -v' is POSIX-standard, unlike 'which'
+        await execFileAsync('sh', ['-c', 'command -v secret-tool'], { timeout: 5_000 });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/auth/WinCredBackend.d.ts

@@ -0,0 +1,19 @@
+import type { CredentialBackend, StoredCredential } from './CredentialBackend.js';
+/**
+ * Windows Credential Manager backend.
+ * Uses PowerShell P/Invoke to Advapi32.dll for CredRead/CredWrite/CredDelete.
+ * cmdkey cannot read passwords back, so P/Invoke is required.
+ *
+ * Each publisher's credential is stored as a generic credential with:
+ *   target = "canon:{normalized_publisher}"
+ *   credential blob = JSON-serialized StoredCredential (UTF-16)
+ *
+ * Data is passed to PowerShell via stdin to prevent injection attacks.
+ * No user-supplied values are interpolated into PowerShell code.
+ */
+export declare class WinCredBackend implements CredentialBackend {
+    get(publisher: string): Promise<StoredCredential | null>;
+    store(publisher: string, credential: StoredCredential): Promise<void>;
+    remove(publisher: string): Promise<void>;
+    list(): Promise<string[]>;
+}

package/dist/auth/WinCredBackend.js

@@ -0,0 +1,172 @@
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { normalizeHost } from './CredentialBackend.js';
+const execFileAsync = promisify(execFile);
+const TARGET_PREFIX = 'canon:';
+/**
+ * Windows Credential Manager backend.
+ * Uses PowerShell P/Invoke to Advapi32.dll for CredRead/CredWrite/CredDelete.
+ * cmdkey cannot read passwords back, so P/Invoke is required.
+ *
+ * Each publisher's credential is stored as a generic credential with:
+ *   target = "canon:{normalized_publisher}"
+ *   credential blob = JSON-serialized StoredCredential (UTF-16)
+ *
+ * Data is passed to PowerShell via stdin to prevent injection attacks.
+ * No user-supplied values are interpolated into PowerShell code.
+ */
+export class WinCredBackend {
+    async get(publisher) {
+        const target = TARGET_PREFIX + normalizeHost(publisher);
+        // Pass target via stdin, read it with [Console]::In.ReadLine()
+        const script = `
+${PINVOKE_BOOTSTRAP}
+$target = [Console]::In.ReadLine()
+$ptr = [IntPtr]::Zero
+$result = [CredMan]::CredRead($target, 1, 0, [ref]$ptr)
+if (-not $result) { exit 1 }
+try {
+  $cred = [System.Runtime.InteropServices.Marshal]::PtrToStructure($ptr, [Type][CredMan+CREDENTIAL])
+  $bytes = New-Object byte[] $cred.CredentialBlobSize
+  [System.Runtime.InteropServices.Marshal]::Copy($cred.CredentialBlob, $bytes, 0, $cred.CredentialBlobSize)
+  [System.Text.Encoding]::Unicode.GetString($bytes)
+} finally {
+  [CredMan]::CredFree($ptr)
+}`;
+        try {
+            const { stdout } = await runPowerShell(script, target);
+            const trimmed = stdout.trim();
+            if (!trimmed)
+                return null;
+            return JSON.parse(trimmed);
+        }
+        catch {
+            return null;
+        }
+    }
+    async store(publisher, credential) {
+        const target = TARGET_PREFIX + normalizeHost(publisher);
+        const json = JSON.stringify(credential);
+        // Pass target and JSON via stdin, one per line
+        const script = `
+${PINVOKE_BOOTSTRAP}
+$target = [Console]::In.ReadLine()
+$json = [Console]::In.ReadLine()
+$bytes = [System.Text.Encoding]::Unicode.GetBytes($json)
+$cred = New-Object CredMan+CREDENTIAL
+$cred.Type = 1
+$cred.TargetName = $target
+$cred.CredentialBlobSize = $bytes.Length
+$cred.CredentialBlob = [System.Runtime.InteropServices.Marshal]::AllocHGlobal($bytes.Length)
+try {
+  [System.Runtime.InteropServices.Marshal]::Copy($bytes, 0, $cred.CredentialBlob, $bytes.Length)
+  $cred.Persist = 2
+  $result = [CredMan]::CredWrite([ref]$cred, 0)
+  if (-not $result) { throw "CredWrite failed" }
+} finally {
+  [System.Runtime.InteropServices.Marshal]::FreeHGlobal($cred.CredentialBlob)
+}`;
+        try {
+            await runPowerShell(script, `${target}\n${json}`);
+        }
+        catch (err) {
+            throw new Error(`Windows Credential Manager write failed: ${String(err)}`);
+        }
+    }
+    async remove(publisher) {
+        const target = TARGET_PREFIX + normalizeHost(publisher);
+        const script = `
+${PINVOKE_BOOTSTRAP}
+$target = [Console]::In.ReadLine()
+[CredMan]::CredDelete($target, 1, 0) | Out-Null`;
+        try {
+            await runPowerShell(script, target);
+        }
+        catch {
+            // Ignore errors (credential may not exist)
+        }
+    }
+    async list() {
+        // Enumerate credentials via P/Invoke CredEnumerate for reliable results
+        // across all Windows locales (cmdkey output is locale-dependent).
+        const script = `
+${PINVOKE_BOOTSTRAP}
+${CRED_ENUMERATE_BOOTSTRAP}
+$prefix = [Console]::In.ReadLine()
+$count = 0
+$pCreds = [IntPtr]::Zero
+if ([CredMan]::CredEnumerate($null, 0, [ref]$count, [ref]$pCreds)) {
+  $ptrSize = [System.Runtime.InteropServices.Marshal]::SizeOf([Type][IntPtr])
+  for ($i = 0; $i -lt $count; $i++) {
+    $credPtr = [System.Runtime.InteropServices.Marshal]::ReadIntPtr($pCreds, $i * $ptrSize)
+    $cred = [System.Runtime.InteropServices.Marshal]::PtrToStructure($credPtr, [Type][CredMan+CREDENTIAL])
+    if ($cred.TargetName -and $cred.TargetName.StartsWith($prefix)) {
+      $cred.TargetName.Substring($prefix.Length)
+    }
+  }
+  [CredMan]::CredFree($pCreds)
+}`;
+        try {
+            const { stdout } = await runPowerShell(script, TARGET_PREFIX);
+            return stdout.trim().split('\n').map(s => s.trim()).filter(Boolean);
+        }
+        catch {
+            return [];
+        }
+    }
+}
+async function runPowerShell(script, stdin) {
+    // Try pwsh (PowerShell 7+) first, fall back to powershell (5.1)
+    for (const shell of ['pwsh', 'powershell']) {
+        try {
+            return await execFileAsync(shell, [
+                '-NoProfile',
+                '-NonInteractive',
+                '-Command',
+                script,
+            ], {
+                timeout: 15_000,
+                ...(stdin !== undefined && { input: stdin }),
+            });
+        }
+        catch (err) {
+            if (shell === 'powershell')
+                throw err;
+            // pwsh not found, try powershell
+        }
+    }
+    throw new Error('Neither pwsh nor powershell found');
+}
+const PINVOKE_BOOTSTRAP = `
+Add-Type -TypeDefinition @"
+using System;
+using System.Runtime.InteropServices;
+public class CredMan {
+  [StructLayout(LayoutKind.Sequential, CharSet = CharSet.Unicode)]
+  public struct CREDENTIAL {
+    public int Flags;
+    public int Type;
+    public string TargetName;
+    public string Comment;
+    public long LastWritten;
+    public int CredentialBlobSize;
+    public IntPtr CredentialBlob;
+    public int Persist;
+    public int AttributeCount;
+    public IntPtr Attributes;
+    public string TargetAlias;
+    public string UserName;
+  }
+  [DllImport("Advapi32.dll", SetLastError = true, CharSet = CharSet.Unicode)]
+  public static extern bool CredRead(string target, int type, int flags, out IntPtr credential);
+  [DllImport("Advapi32.dll", SetLastError = true, CharSet = CharSet.Unicode)]
+  public static extern bool CredWrite(ref CREDENTIAL credential, int flags);
+  [DllImport("Advapi32.dll", SetLastError = true)]
+  public static extern bool CredDelete(string target, int type, int flags);
+  [DllImport("Advapi32.dll", SetLastError = true)]
+  public static extern void CredFree(IntPtr buffer);
+  [DllImport("Advapi32.dll", SetLastError = true, CharSet = CharSet.Unicode)]
+  public static extern bool CredEnumerate(string filter, int flags, out int count, out IntPtr credentials);
+}
+"@`;
+const CRED_ENUMERATE_BOOTSTRAP = ''; // CredEnumerate is already in the P/Invoke bootstrap above

package/dist/auth/index.d.ts

@@ -0,0 +1,11 @@
+export type { CredentialBackend, StoredCredential, DPoPKeyPair } from './CredentialBackend.js';
+export { isExpired, hasValidToken, normalizeHost } from './CredentialBackend.js';
+export { CredentialStore } from './CredentialStore.js';
+export type { AuthenticatedFetchFn } from './AuthenticatedFetch.js';
+export { createAuthenticatedFetch } from './AuthenticatedFetch.js';
+export { generateDPoPKeyPair, createDPoPProof, serverSupportsDPoP } from './DPoP.js';
+export { KeychainBackend } from './KeychainBackend.js';
+export { WinCredBackend } from './WinCredBackend.js';
+export { SecretServiceBackend, hasSecretTool } from './SecretServiceBackend.js';
+export { EncryptedFileBackend } from './EncryptedFileBackend.js';
+export { CredentialHelperBackend } from './CredentialHelperBackend.js';

package/dist/auth/index.js

@@ -0,0 +1,9 @@
+export { isExpired, hasValidToken, normalizeHost } from './CredentialBackend.js';
+export { CredentialStore } from './CredentialStore.js';
+export { createAuthenticatedFetch } from './AuthenticatedFetch.js';
+export { generateDPoPKeyPair, createDPoPProof, serverSupportsDPoP } from './DPoP.js';
+export { KeychainBackend } from './KeychainBackend.js';
+export { WinCredBackend } from './WinCredBackend.js';
+export { SecretServiceBackend, hasSecretTool } from './SecretServiceBackend.js';
+export { EncryptedFileBackend } from './EncryptedFileBackend.js';
+export { CredentialHelperBackend } from './CredentialHelperBackend.js';

package/dist/index.d.ts

@@ -15,5 +15,7 @@ export type { ICanonDocumentRepository } from '@canon-protocol/types/document/mo
 export type { ICanonParser } from '@canon-protocol/types/document/parsing';
 export type { CanonDocument, CanonMetadata, Namespace, Import, Version, DocumentReference, ParseResult, ParseError } from '@canon-protocol/types/document/models/types';
 export type { VersionOperator } from '@canon-protocol/types/document/models/enums';
+export { CredentialStore, createAuthenticatedFetch, generateDPoPKeyPair, createDPoPProof, serverSupportsDPoP, isExpired, hasValidToken, normalizeHost, } from './auth/index.js';
+export type { CredentialBackend, StoredCredential, DPoPKeyPair, AuthenticatedFetchFn, } from './auth/index.js';
 export { CtlCanonUri, CtlParser, ResourceTypeClassifier, CtlValidator, CtlGraphResolver, CtlMarkdownRenderer, CtlValidationErrorType, CtlValidationSeverity, CtlCanonUriType, PathSegmentType, ResolvedResourceType } from './ctl/index.js';
 export type { CtlDocument, CanonReference, CtlValidationResult, CtlValidationError, ResolvedResourceGraph, ResolvedResource, ResolvedProperty, UnresolvedResource } from './ctl/index.js';

package/dist/index.js

@@ -5,4 +5,5 @@ export { ResourceResolver, CanonUri, CanonUriBuilder, TypeResolver } from './res
 export { Canon, DefinedCanon, SubjectCanon, EmbeddedCanon, ReferenceCanon } from './canons/index.js';
 export { Statement, ScalarStatement, StringStatement, NumberStatement, BooleanStatement, ReferenceStatement, EmbeddedStatement, ListStatement } from './statements/index.js';
 export { OntologyValidationResult, OntologyValidationError, ValidationSeverity, ValidationContext, CanonObjectValidator, NamespacePrefixRule, ResourceNamingRule, PropertyTypeSpecificityRule, SubjectCanonTypeRequiredRule, EmbeddedCanonNoExplicitTypeRule, ImportExistenceRule, UnresolvedReferenceRule, TypeAmbiguityRule, ClassHierarchyCycleRule, PropertyHierarchyCycleRule, PropertyRangeRequiredRule, SubClassOfReferenceRule, SubPropertyOfReferenceRule, NamespaceImportCycleRule, InstancePropertyReferenceRule, DefinitionPropertyReferenceRule, XsdImportRule, AmbiguousReferenceRule, PropertyRangeReferenceRule, ObjectPropertyImportRule, ObjectPropertyValueValidationRule, PropertyDomainRule, PropertyValueTypeRule, ClassDefinitionRule } from './validation/index.js';
+export { CredentialStore, createAuthenticatedFetch, generateDPoPKeyPair, createDPoPProof, serverSupportsDPoP, isExpired, hasValidToken, normalizeHost, } from './auth/index.js';
 export { CtlCanonUri, CtlParser, ResourceTypeClassifier, CtlValidator, CtlGraphResolver, CtlMarkdownRenderer, CtlValidationErrorType, CtlValidationSeverity, CtlCanonUriType, PathSegmentType, ResolvedResourceType } from './ctl/index.js';

package/dist/repositories/HttpCanonDocumentRepository.d.ts

@@ -1,15 +1,18 @@
 import type { ICanonDocumentRepository } from '@canon-protocol/types/document/models';
 import type { CanonDocument, Import, DocumentReference } from '@canon-protocol/types/document/models/types';
+import type { AuthenticatedFetchFn } from '../auth/index.js';
 export declare class HttpCanonDocumentRepository implements ICanonDocumentRepository {
     private readonly parser;
     private readonly publisherIndex;
     private readonly documents;
     private readonly contentCache;
+    private readonly fetchFn;
     private readonly onFetch;
     private readonly getFromCache;
     constructor(options?: {
         onFetch?: (publisher: string, packageName: string, version: string, content: string) => void;
         getFromCache?: (publisher: string, packageName: string, version: string) => string | null;
+        fetchFn?: AuthenticatedFetchFn;
     });
     getHighestCompatibleVersionAsync(publisher: string, import_: Import): Promise<CanonDocument | null>;
     getAllDocumentsAsync(): Promise<CanonDocument[]>;

package/dist/repositories/HttpCanonDocumentRepository.js

@@ -2,14 +2,19 @@ import { CanonParser } from '../parsing/CanonParser.js';
 import { PublisherIndex } from './PublisherIndex.js';
 export class HttpCanonDocumentRepository {
     parser = new CanonParser();
-    publisherIndex = new PublisherIndex();
+    publisherIndex;
     documents = new Map();
     contentCache = new Map();
+    fetchFn;
     onFetch;
     getFromCache;
     constructor(options) {
         this.onFetch = options?.onFetch;
         this.getFromCache = options?.getFromCache;
+        this.fetchFn = options?.fetchFn;
+        this.publisherIndex = options?.fetchFn
+            ? new PublisherIndex({ fetchFn: options.fetchFn })
+            : new PublisherIndex();
     }
     async getHighestCompatibleVersionAsync(publisher, import_) {
         const version = await this.publisherIndex.resolveVersion(publisher, import_);
@@ -29,7 +34,9 @@ export class HttpCanonDocumentRepository {
             }
         }
         const url = await this.publisherIndex.getPackageUrl(publisher, import_.packageName, version);
-        const response = await fetch(url);
+        const response = this.fetchFn
+            ? await this.fetchFn(url, publisher)
+            : await fetch(url);
         if (!response.ok) {
             throw new Error(`Failed to fetch Canon package: ${url} (${response.status} ${response.statusText})`);
         }

package/dist/repositories/PublisherConfig.d.ts

@@ -2,6 +2,7 @@ export interface PublisherConfig {
     version: number;
     index?: string;
     package?: string;
+    auth?: 'none' | 'oauth' | 'bearer';
 }
 export declare class PublisherConfigResolver {
     private readonly cache;

package/dist/repositories/PublisherConfig.js

@@ -38,6 +38,9 @@ export class PublisherConfigResolver {
         if (typeof json.package === 'string') {
             config.package = json.package;
         }
+        if (json.auth === 'none' || json.auth === 'oauth' || json.auth === 'bearer') {
+            config.auth = json.auth;
+        }
         return config;
     }
     resolveIndexUrl(publisher, config) {

package/dist/repositories/PublisherIndex.d.ts

@@ -1,9 +1,14 @@
 import type { Import } from '@canon-protocol/types/document/models/types';
 import { PublisherConfigResolver } from './PublisherConfig.js';
+import type { AuthenticatedFetchFn } from '../auth/index.js';
 export declare class PublisherIndex {
     private readonly indexCache;
     private readonly configResolver;
-    constructor(configResolver?: PublisherConfigResolver);
+    private readonly fetchFn;
+    constructor(options?: {
+        configResolver?: PublisherConfigResolver;
+        fetchFn?: AuthenticatedFetchFn;
+    });
     resolveVersion(publisher: string, import_: Import): Promise<string | null>;
     getHighestVersion(publisher: string, packageName: string): Promise<string | null>;
     getPackageUrl(publisher: string, packageName: string, version: string): Promise<string>;

package/dist/repositories/PublisherIndex.js

@@ -3,8 +3,10 @@ import { PublisherConfigResolver } from './PublisherConfig.js';
 export class PublisherIndex {
     indexCache = new Map();
     configResolver;
-    constructor(configResolver) {
-        this.configResolver = configResolver ?? new PublisherConfigResolver();
+    fetchFn;
+    constructor(options) {
+        this.configResolver = options?.configResolver ?? new PublisherConfigResolver();
+        this.fetchFn = options?.fetchFn;
     }
     async resolveVersion(publisher, import_) {
         const packageVersions = await this.getPackageVersions(publisher, import_.packageName);
@@ -40,7 +42,9 @@ export class PublisherIndex {
     async fetchIndex(publisher) {
         const config = await this.configResolver.getConfig(publisher);
         const url = this.configResolver.resolveIndexUrl(publisher, config);
-        const response = await fetch(url);
+        const response = this.fetchFn
+            ? await this.fetchFn(url, publisher)
+            : await fetch(url);
         if (!response.ok) {
             throw new Error(`Failed to fetch publisher index: ${url} (${response.status} ${response.statusText})`);
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@canon-protocol/sdk",
-  "version": "8.0.1",
+  "version": "8.1.0",
   "description": "Canon Protocol SDK - Document repository and parsing implementations for TypeScript",
   "type": "module",
   "main": "./dist/index.js",
@@ -62,7 +62,7 @@
     "yaml-parser"
   ],
   "dependencies": {
-    "@canon-protocol/types": "^8.0.1",
+    "@canon-protocol/types": "^8.1.0",
     "ignore": "^7.0.5",
     "js-yaml": "^4.1.0"
   },