@id-wispera/core 0.1.0

package/dist/auth/sessionTokenManager.js

@@ -0,0 +1,263 @@
+/**
+ * ID Wispera Session Token Manager
+ * Manages short-lived session tokens for headless / CI environments.
+ *
+ * Design:
+ *   - Tokens live in a sidecar file (~/.id-wispera/sessions.json), NOT inside
+ *     the encrypted vault (avoids the chicken-and-egg problem).
+ *   - Each sidecar entry stores the vault passphrase encrypted with a key
+ *     derived from the token itself (PBKDF2 + AES-256-GCM).
+ *   - The token is the only runtime credential needed — set as
+ *     IDW_SESSION_TOKEN env var.
+ *   - If the sidecar is lost or corrupted the user still has their passphrase
+ *     as the root recovery path.
+ *
+ * Token format:
+ *   idw_token_ + 64 random bytes base64url-encoded  (~90 chars total)
+ *
+ * Sidecar schema (cross-SDK compatible — TS, Python, Go all read/write this):
+ *   {
+ *     "version": 1,
+ *     "entries": [
+ *       {
+ *         "tokenHash":            "<SHA-256 hex>",
+ *         "salt":                 "<32 bytes hex>",
+ *         "iv":                   "<12 bytes hex>",
+ *         "encryptedPassphrase":  "<AES-256-GCM ciphertext, base64>",
+ *         "createdAt":            "<ISO 8601>",
+ *         "expiresAt":            "<ISO 8601 | null>",
+ *         "label":                "<user-provided label>"
+ *       }
+ *     ]
+ *   }
+ */
+import { getRandomBytes, getCryptoSubtle, toBufferSource } from '../utils.js';
+// ============================================================================
+// Constants
+// ============================================================================
+const TOKEN_PREFIX = 'idw_token_';
+const TOKEN_RANDOM_BYTES = 64;
+const SIDECAR_VERSION = 1;
+const PBKDF2_ITERATIONS = 100_000;
+const SALT_BYTES = 32;
+const IV_BYTES = 12;
+const ENV_VAR = 'IDW_SESSION_TOKEN';
+// ============================================================================
+// Helpers
+// ============================================================================
+function bytesToHex(bytes) {
+    return Array.from(bytes)
+        .map((b) => b.toString(16).padStart(2, '0'))
+        .join('');
+}
+function hexToBytes(hex) {
+    const bytes = new Uint8Array(hex.length / 2);
+    for (let i = 0; i < hex.length; i += 2) {
+        bytes[i / 2] = parseInt(hex.substr(i, 2), 16);
+    }
+    return bytes;
+}
+function bytesToBase64url(bytes) {
+    // Node.js path
+    if (typeof Buffer !== 'undefined') {
+        return Buffer.from(bytes).toString('base64url');
+    }
+    // Fallback (browser / edge)
+    const base64 = btoa(String.fromCharCode(...bytes));
+    return base64.replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
+}
+function base64urlToBytes(b64) {
+    if (typeof Buffer !== 'undefined') {
+        return new Uint8Array(Buffer.from(b64, 'base64url'));
+    }
+    const padded = b64.replace(/-/g, '+').replace(/_/g, '/');
+    const binary = atob(padded);
+    const bytes = new Uint8Array(binary.length);
+    for (let i = 0; i < binary.length; i++) {
+        bytes[i] = binary.charCodeAt(i);
+    }
+    return bytes;
+}
+async function sha256Hex(data) {
+    const crypto = await getCryptoSubtle();
+    const hash = await crypto.digest('SHA-256', toBufferSource(new TextEncoder().encode(data)));
+    return bytesToHex(new Uint8Array(hash));
+}
+async function deriveTokenKey(token, salt) {
+    const crypto = await getCryptoSubtle();
+    const keyMaterial = await crypto.importKey('raw', toBufferSource(new TextEncoder().encode(token)), 'PBKDF2', false, ['deriveBits', 'deriveKey']);
+    return crypto.deriveKey({
+        name: 'PBKDF2',
+        salt: toBufferSource(salt),
+        iterations: PBKDF2_ITERATIONS,
+        hash: 'SHA-256',
+    }, keyMaterial, { name: 'AES-GCM', length: 256 }, false, ['encrypt', 'decrypt']);
+}
+async function encryptPassphrase(passphrase, token, salt, iv) {
+    const crypto = await getCryptoSubtle();
+    const key = await deriveTokenKey(token, salt);
+    const ciphertext = await crypto.encrypt({ name: 'AES-GCM', iv: toBufferSource(iv) }, key, toBufferSource(new TextEncoder().encode(passphrase)));
+    return bytesToBase64url(new Uint8Array(ciphertext));
+}
+async function decryptPassphrase(encryptedBase64, token, salt, iv) {
+    const crypto = await getCryptoSubtle();
+    const key = await deriveTokenKey(token, salt);
+    const plaintext = await crypto.decrypt({ name: 'AES-GCM', iv: toBufferSource(iv) }, key, toBufferSource(base64urlToBytes(encryptedBase64)));
+    return new TextDecoder().decode(plaintext);
+}
+// ============================================================================
+// Session Token Manager
+// ============================================================================
+export class SessionTokenManager {
+    sidecarPath;
+    constructor(sidecarPath) {
+        const home = process.env.HOME ?? process.env.USERPROFILE ?? '.';
+        this.sidecarPath = sidecarPath ?? `${home}/.id-wispera/sessions.json`;
+    }
+    /** Read the sidecar file.  Returns an empty structure if missing/corrupt. */
+    async readSidecar() {
+        const fs = await import('fs/promises');
+        try {
+            const content = await fs.readFile(this.sidecarPath, 'utf-8');
+            const data = JSON.parse(content);
+            if (data.version !== SIDECAR_VERSION || !Array.isArray(data.entries)) {
+                return { version: SIDECAR_VERSION, entries: [] };
+            }
+            return data;
+        }
+        catch {
+            return { version: SIDECAR_VERSION, entries: [] };
+        }
+    }
+    /** Write the sidecar file, creating parent directories as needed. */
+    async writeSidecar(data) {
+        const fs = await import('fs/promises');
+        const path = await import('path');
+        await fs.mkdir(path.dirname(this.sidecarPath), { recursive: true });
+        await fs.writeFile(this.sidecarPath, JSON.stringify(data, null, 2), {
+            encoding: 'utf-8',
+            mode: 0o600, // owner read/write only
+        });
+    }
+    // --------------------------------------------------------------------------
+    // Public API
+    // --------------------------------------------------------------------------
+    /**
+     * Generate a new CSPRNG token string.
+     */
+    generateToken() {
+        const randomBytes = getRandomBytes(TOKEN_RANDOM_BYTES);
+        return TOKEN_PREFIX + bytesToBase64url(randomBytes);
+    }
+    /**
+     * Create a session token entry.  Encrypts the passphrase with a key
+     * derived from the token and stores the entry in the sidecar file.
+     *
+     * @returns The plaintext token (shown to the user once — never stored).
+     */
+    async create(passphrase, options = {}) {
+        const token = this.generateToken();
+        const tokenHash = await sha256Hex(token);
+        const salt = getRandomBytes(SALT_BYTES);
+        const iv = getRandomBytes(IV_BYTES);
+        const encrypted = await encryptPassphrase(passphrase, token, salt, iv);
+        const now = new Date();
+        const expiresAt = options.expiresInSeconds
+            ? new Date(now.getTime() + options.expiresInSeconds * 1000).toISOString()
+            : null;
+        const entry = {
+            tokenHash,
+            salt: bytesToHex(salt),
+            iv: bytesToHex(iv),
+            encryptedPassphrase: encrypted,
+            createdAt: now.toISOString(),
+            expiresAt,
+            label: options.label ?? 'default',
+        };
+        const sidecar = await this.readSidecar();
+        sidecar.entries.push(entry);
+        await this.writeSidecar(sidecar);
+        return token;
+    }
+    /**
+     * Resolve a session token → vault passphrase.
+     *
+     * Looks up the sidecar entry by the token's SHA-256 hash, checks expiry,
+     * then decrypts the passphrase.
+     *
+     * @throws Error if the token is invalid, expired, or sidecar is missing.
+     */
+    async resolve(token) {
+        if (!token.startsWith(TOKEN_PREFIX)) {
+            throw new Error('Invalid session token format.');
+        }
+        const tokenHash = await sha256Hex(token);
+        const sidecar = await this.readSidecar();
+        const entry = sidecar.entries.find((e) => e.tokenHash === tokenHash);
+        if (!entry) {
+            throw new Error('Session token not found. It may have been revoked or the sidecar file is missing. ' +
+                "Use your passphrase directly, or create a new token with 'idw auth token create'.");
+        }
+        // Check expiry
+        if (entry.expiresAt && new Date(entry.expiresAt) < new Date()) {
+            throw new Error('Session token has expired. ' +
+                "Create a new token with 'idw auth token create'.");
+        }
+        try {
+            return await decryptPassphrase(entry.encryptedPassphrase, token, hexToBytes(entry.salt), hexToBytes(entry.iv));
+        }
+        catch {
+            throw new Error('Failed to decrypt passphrase from session token. The sidecar entry may be corrupt. ' +
+                "Use your passphrase directly, or create a new token with 'idw auth token create'.");
+        }
+    }
+    /**
+     * Revoke a session token by its hash prefix (first 8+ hex chars).
+     * Returns `true` if an entry was removed.
+     */
+    async revoke(hashPrefix) {
+        const sidecar = await this.readSidecar();
+        const before = sidecar.entries.length;
+        sidecar.entries = sidecar.entries.filter((e) => !e.tokenHash.startsWith(hashPrefix));
+        if (sidecar.entries.length === before)
+            return false;
+        await this.writeSidecar(sidecar);
+        return true;
+    }
+    /**
+     * List all session tokens (metadata only — never returns secrets).
+     * Expired entries are included but marked.
+     */
+    async list() {
+        const sidecar = await this.readSidecar();
+        return sidecar.entries.map((e) => ({
+            tokenHash: e.tokenHash,
+            label: e.label,
+            createdAt: e.createdAt,
+            expiresAt: e.expiresAt,
+        }));
+    }
+    /**
+     * Remove all expired entries from the sidecar.
+     * Returns the number of entries removed.
+     */
+    async pruneExpired() {
+        const sidecar = await this.readSidecar();
+        const before = sidecar.entries.length;
+        const now = new Date();
+        sidecar.entries = sidecar.entries.filter((e) => !e.expiresAt || new Date(e.expiresAt) >= now);
+        const removed = before - sidecar.entries.length;
+        if (removed > 0)
+            await this.writeSidecar(sidecar);
+        return removed;
+    }
+    /**
+     * Read the token from the environment variable.
+     * Returns `null` if not set.
+     */
+    static getTokenFromEnv() {
+        return process.env[ENV_VAR] ?? null;
+    }
+}
+export { ENV_VAR as SESSION_TOKEN_ENV_VAR };
+//# sourceMappingURL=sessionTokenManager.js.map

package/dist/auth/sessionTokenManager.js.map

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

package/dist/delegation.d.ts

@@ -0,0 +1,81 @@
+/**
+ * ID Wispera Delegation Chain Management
+ * Track credential provenance through agent delegation
+ */
+import { Passport, DelegationHop } from './types.js';
+import { Vault } from './vault.js';
+/**
+ * Add a delegation hop to a passport
+ */
+export declare function addDelegation(vault: Vault, passportId: string, delegation: Omit<DelegationHop, 'grantedAt'>, actor: string): Promise<Passport>;
+/**
+ * Remove the last delegation hop from a passport
+ */
+export declare function revokeDelegation(vault: Vault, passportId: string, actor: string): Promise<Passport>;
+/**
+ * Clear all delegations from a passport
+ */
+export declare function clearDelegations(vault: Vault, passportId: string, actor: string): Promise<Passport>;
+/**
+ * Get the delegation depth of a passport
+ */
+export declare function getDelegationDepth(passport: Passport): number;
+/**
+ * Get the current holder (last in delegation chain, or human owner if no chain)
+ */
+export declare function getCurrentHolder(passport: Passport): string;
+/**
+ * Get the original issuer (human owner)
+ */
+export declare function getOriginalIssuer(passport: Passport): string;
+/**
+ * Get all entities in the delegation chain (including owner)
+ */
+export declare function getAllDelegationParties(passport: Passport): string[];
+/**
+ * Check if an entity is in the delegation chain
+ */
+export declare function isInDelegationChain(passport: Passport, entity: string): boolean;
+/**
+ * Get the delegation path as a readable string
+ */
+export declare function getDelegationPath(passport: Passport): string;
+/**
+ * Check if any delegation in the chain has expired
+ */
+export declare function hasExpiredDelegation(passport: Passport): boolean;
+/**
+ * Get expired delegations
+ */
+export declare function getExpiredDelegations(passport: Passport): DelegationHop[];
+/**
+ * Get delegations expiring soon (within specified days)
+ */
+export declare function getExpiringDelegations(passport: Passport, withinDays?: number): DelegationHop[];
+/**
+ * Get the effective scope (intersection of all delegated scopes)
+ */
+export declare function getEffectiveScope(passport: Passport): string[];
+/**
+ * Check if a specific scope is permitted through the delegation chain
+ */
+export declare function isScopePermitted(passport: Passport, scope: string): boolean;
+/**
+ * Get scope restrictions applied by delegations
+ */
+export declare function getScopeRestrictions(passport: Passport): {
+    originalScope: string[];
+    effectiveScope: string[];
+    restrictedBy: Array<{
+        hop: DelegationHop;
+        removedScopes: string[];
+    }>;
+};
+/**
+ * Validate a delegation chain
+ */
+export declare function validateDelegationChain(passport: Passport): {
+    valid: boolean;
+    issues: string[];
+};
+//# sourceMappingURL=delegation.d.ts.map

package/dist/delegation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"delegation.d.ts","sourceRoot":"","sources":["../src/delegation.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EACL,QAAQ,EACR,aAAa,EAEd,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAOnC;;GAEG;AACH,wBAAsB,aAAa,CACjC,KAAK,EAAE,KAAK,EACZ,UAAU,EAAE,MAAM,EAClB,UAAU,EAAE,IAAI,CAAC,aAAa,EAAE,WAAW,CAAC,EAC5C,KAAK,EAAE,MAAM,GACZ,OAAO,CAAC,QAAQ,CAAC,CAkCnB;AAED;;GAEG;AACH,wBAAsB,gBAAgB,CACpC,KAAK,EAAE,KAAK,EACZ,UAAU,EAAE,MAAM,EAClB,KAAK,EAAE,MAAM,GACZ,OAAO,CAAC,QAAQ,CAAC,CAgCnB;AAED;;GAEG;AACH,wBAAsB,gBAAgB,CACpC,KAAK,EAAE,KAAK,EACZ,UAAU,EAAE,MAAM,EAClB,KAAK,EAAE,MAAM,GACZ,OAAO,CAAC,QAAQ,CAAC,CA2BnB;AAMD;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,QAAQ,GAAG,MAAM,CAE7D;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,QAAQ,GAAG,MAAM,CAK3D;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,QAAQ,GAAG,MAAM,CAE5D;AAED;;GAEG;AACH,wBAAgB,uBAAuB,CAAC,QAAQ,EAAE,QAAQ,GAAG,MAAM,EAAE,CAWpE;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAU/E;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,QAAQ,GAAG,MAAM,CAU5D;AAED;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,QAAQ,GAAG,OAAO,CAOhE;AAED;;GAEG;AACH,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,QAAQ,GAAG,aAAa,EAAE,CAOzE;AAED;;GAEG;AACH,wBAAgB,sBAAsB,CACpC,QAAQ,EAAE,QAAQ,EAClB,UAAU,GAAE,MAAU,GACrB,aAAa,EAAE,CAWjB;AAMD;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,QAAQ,GAAG,MAAM,EAAE,CAiB9D;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAG3E;AAED;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,QAAQ,GAAG;IACxD,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,cAAc,EAAE,MAAM,EAAE,CAAC;IACzB,YAAY,EAAE,KAAK,CAAC;QAAE,GAAG,EAAE,aAAa,CAAC;QAAC,aAAa,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC,CAAC;CACtE,CAyBA;AAMD;;GAEG;AACH,wBAAgB,uBAAuB,CAAC,QAAQ,EAAE,QAAQ,GAAG;IAC3D,KAAK,EAAE,OAAO,CAAC;IACf,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB,CAmDA"}

package/dist/delegation.js

@@ -0,0 +1,299 @@
+/**
+ * ID Wispera Delegation Chain Management
+ * Track credential provenance through agent delegation
+ */
+import { WisperaError, } from './types.js';
+import { logAction } from './audit.js';
+// ============================================================================
+// Delegation Chain Operations
+// ============================================================================
+/**
+ * Add a delegation hop to a passport
+ */
+export async function addDelegation(vault, passportId, delegation, actor) {
+    const passport = await vault.retrievePassport(passportId);
+    if (!passport) {
+        throw new WisperaError(`Passport not found: ${passportId}`, 'PASSPORT_NOT_FOUND');
+    }
+    const hop = {
+        ...delegation,
+        grantedAt: new Date().toISOString(),
+    };
+    const updatedChain = [...(passport.delegationChain ?? []), hop];
+    const updated = {
+        ...passport,
+        delegationChain: updatedChain,
+        updatedAt: new Date().toISOString(),
+    };
+    await vault.storePassport(updated);
+    await logAction(vault, {
+        passportId,
+        action: 'modified',
+        actor,
+        details: `Delegated credential from "${delegation.from}" to "${delegation.to}"`,
+        metadata: {
+            delegationFrom: delegation.from,
+            delegationTo: delegation.to,
+            delegationScope: delegation.scope,
+        },
+    });
+    return updated;
+}
+/**
+ * Remove the last delegation hop from a passport
+ */
+export async function revokeDelegation(vault, passportId, actor) {
+    const passport = await vault.retrievePassport(passportId);
+    if (!passport) {
+        throw new WisperaError(`Passport not found: ${passportId}`, 'PASSPORT_NOT_FOUND');
+    }
+    if (!passport.delegationChain || passport.delegationChain.length === 0) {
+        throw new WisperaError('No delegation to revoke', 'NO_DELEGATION');
+    }
+    const revokedHop = passport.delegationChain[passport.delegationChain.length - 1];
+    const updatedChain = passport.delegationChain.slice(0, -1);
+    const updated = {
+        ...passport,
+        delegationChain: updatedChain.length > 0 ? updatedChain : undefined,
+        updatedAt: new Date().toISOString(),
+    };
+    await vault.storePassport(updated);
+    await logAction(vault, {
+        passportId,
+        action: 'modified',
+        actor,
+        details: `Revoked delegation from "${revokedHop?.from}" to "${revokedHop?.to}"`,
+        metadata: {
+            revokedDelegation: revokedHop,
+        },
+    });
+    return updated;
+}
+/**
+ * Clear all delegations from a passport
+ */
+export async function clearDelegations(vault, passportId, actor) {
+    const passport = await vault.retrievePassport(passportId);
+    if (!passport) {
+        throw new WisperaError(`Passport not found: ${passportId}`, 'PASSPORT_NOT_FOUND');
+    }
+    const previousChain = passport.delegationChain;
+    const updated = {
+        ...passport,
+        delegationChain: undefined,
+        updatedAt: new Date().toISOString(),
+    };
+    await vault.storePassport(updated);
+    await logAction(vault, {
+        passportId,
+        action: 'modified',
+        actor,
+        details: `Cleared all delegations (${previousChain?.length ?? 0} hops removed)`,
+        metadata: {
+            clearedDelegations: previousChain,
+        },
+    });
+    return updated;
+}
+// ============================================================================
+// Delegation Chain Analysis
+// ============================================================================
+/**
+ * Get the delegation depth of a passport
+ */
+export function getDelegationDepth(passport) {
+    return passport.delegationChain?.length ?? 0;
+}
+/**
+ * Get the current holder (last in delegation chain, or human owner if no chain)
+ */
+export function getCurrentHolder(passport) {
+    if (!passport.delegationChain || passport.delegationChain.length === 0) {
+        return passport.humanOwner;
+    }
+    return passport.delegationChain[passport.delegationChain.length - 1]?.to ?? passport.humanOwner;
+}
+/**
+ * Get the original issuer (human owner)
+ */
+export function getOriginalIssuer(passport) {
+    return passport.humanOwner;
+}
+/**
+ * Get all entities in the delegation chain (including owner)
+ */
+export function getAllDelegationParties(passport) {
+    const seen = new Set([passport.humanOwner]);
+    if (passport.delegationChain) {
+        for (const hop of passport.delegationChain) {
+            seen.add(hop.from);
+            seen.add(hop.to);
+        }
+    }
+    return Array.from(seen);
+}
+/**
+ * Check if an entity is in the delegation chain
+ */
+export function isInDelegationChain(passport, entity) {
+    if (passport.humanOwner === entity)
+        return true;
+    if (passport.delegationChain) {
+        for (const hop of passport.delegationChain) {
+            if (hop.from === entity || hop.to === entity)
+                return true;
+        }
+    }
+    return false;
+}
+/**
+ * Get the delegation path as a readable string
+ */
+export function getDelegationPath(passport) {
+    const parts = [passport.humanOwner];
+    if (passport.delegationChain) {
+        for (const hop of passport.delegationChain) {
+            parts.push(hop.to);
+        }
+    }
+    return parts.join(' → ');
+}
+/**
+ * Check if any delegation in the chain has expired
+ */
+export function hasExpiredDelegation(passport) {
+    if (!passport.delegationChain)
+        return false;
+    const now = new Date();
+    return passport.delegationChain.some((hop) => hop.expiresAt && new Date(hop.expiresAt) < now);
+}
+/**
+ * Get expired delegations
+ */
+export function getExpiredDelegations(passport) {
+    if (!passport.delegationChain)
+        return [];
+    const now = new Date();
+    return passport.delegationChain.filter((hop) => hop.expiresAt && new Date(hop.expiresAt) < now);
+}
+/**
+ * Get delegations expiring soon (within specified days)
+ */
+export function getExpiringDelegations(passport, withinDays = 7) {
+    if (!passport.delegationChain)
+        return [];
+    const now = new Date();
+    const threshold = new Date(now.getTime() + withinDays * 24 * 60 * 60 * 1000);
+    return passport.delegationChain.filter((hop) => {
+        if (!hop.expiresAt)
+            return false;
+        const expiresAt = new Date(hop.expiresAt);
+        return expiresAt > now && expiresAt <= threshold;
+    });
+}
+// ============================================================================
+// Delegation Scope Analysis
+// ============================================================================
+/**
+ * Get the effective scope (intersection of all delegated scopes)
+ */
+export function getEffectiveScope(passport) {
+    // Start with the passport's full scope
+    let effectiveScope = new Set(passport.scope);
+    // Each delegation can only narrow, not expand the scope
+    if (passport.delegationChain) {
+        for (const hop of passport.delegationChain) {
+            if (hop.scope && hop.scope.length > 0) {
+                const delegatedScope = new Set(hop.scope);
+                for (const s of effectiveScope) {
+                    if (!delegatedScope.has(s))
+                        effectiveScope.delete(s);
+                }
+            }
+        }
+    }
+    return Array.from(effectiveScope);
+}
+/**
+ * Check if a specific scope is permitted through the delegation chain
+ */
+export function isScopePermitted(passport, scope) {
+    const effectiveScope = getEffectiveScope(passport);
+    return effectiveScope.includes(scope);
+}
+/**
+ * Get scope restrictions applied by delegations
+ */
+export function getScopeRestrictions(passport) {
+    const originalScope = passport.scope;
+    let currentScope = new Set(originalScope);
+    const restrictedBy = [];
+    if (passport.delegationChain) {
+        for (const hop of passport.delegationChain) {
+            if (hop.scope && hop.scope.length > 0) {
+                const delegatedScope = new Set(hop.scope);
+                const removedScopes = [...currentScope].filter((s) => !delegatedScope.has(s));
+                if (removedScopes.length > 0) {
+                    restrictedBy.push({ hop, removedScopes });
+                }
+                currentScope = new Set([...currentScope].filter((s) => delegatedScope.has(s)));
+            }
+        }
+    }
+    return {
+        originalScope,
+        effectiveScope: Array.from(currentScope),
+        restrictedBy,
+    };
+}
+// ============================================================================
+// Delegation Validation
+// ============================================================================
+/**
+ * Validate a delegation chain
+ */
+export function validateDelegationChain(passport) {
+    const issues = [];
+    if (!passport.delegationChain || passport.delegationChain.length === 0) {
+        return { valid: true, issues: [] };
+    }
+    // Check for circular delegations
+    const seen = new Set([passport.humanOwner]);
+    for (const hop of passport.delegationChain) {
+        if (seen.has(hop.to)) {
+            issues.push(`Circular delegation detected: "${hop.to}" appears multiple times`);
+        }
+        seen.add(hop.to);
+    }
+    // Check for broken chain (from should match previous to)
+    let expectedFrom = passport.humanOwner;
+    for (let i = 0; i < passport.delegationChain.length; i++) {
+        const hop = passport.delegationChain[i];
+        if (hop && hop.from !== expectedFrom) {
+            issues.push(`Broken chain at hop ${i + 1}: expected from "${expectedFrom}", got "${hop.from}"`);
+        }
+        expectedFrom = hop?.to ?? expectedFrom;
+    }
+    // Check for expired delegations
+    const expired = getExpiredDelegations(passport);
+    if (expired.length > 0) {
+        issues.push(`${expired.length} delegation(s) have expired`);
+    }
+    // Check delegation timestamps are in order
+    let lastTimestamp = null;
+    for (let i = 0; i < passport.delegationChain.length; i++) {
+        const hop = passport.delegationChain[i];
+        if (hop) {
+            const hopTime = new Date(hop.grantedAt);
+            if (lastTimestamp && hopTime < lastTimestamp) {
+                issues.push(`Delegation timestamp out of order at hop ${i + 1}`);
+            }
+            lastTimestamp = hopTime;
+        }
+    }
+    return {
+        valid: issues.length === 0,
+        issues,
+    };
+}
+//# sourceMappingURL=delegation.js.map