@tinycloud/sdk-core 2.0.0 → 2.0.2-beta.0

package/dist/authorization/CapabilityKeyRegistry.d.ts

@@ -1,317 +0,0 @@
-/**
- * CapabilityKeyRegistry - Tracks keys and their capabilities for automatic key selection.
- *
- * The registry maintains mappings between:
- * - Keys and their associated delegations
- * - Capabilities (resource/action pairs) and the keys that can exercise them
- *
- * This enables automatic key selection when performing operations, choosing
- * the most appropriate key based on priority and validity.
- *
- * @packageDocumentation
- */
-import type { Result, ServiceError } from "@tinycloud/sdk-services";
-import type { KeyInfo, CapabilityEntry, Delegation, IngestOptions } from "../delegations/types";
-/**
- * Error codes specific to CapabilityKeyRegistry operations.
- */
-export declare const CapabilityKeyRegistryErrorCodes: {
-    /** Key not found in registry */
-    readonly KEY_NOT_FOUND: "KEY_NOT_FOUND";
-    /** No key available for the requested capability */
-    readonly NO_CAPABLE_KEY: "NO_CAPABLE_KEY";
-    /** Delegation has expired */
-    readonly DELEGATION_EXPIRED: "DELEGATION_EXPIRED";
-    /** Delegation has been revoked */
-    readonly DELEGATION_REVOKED: "DELEGATION_REVOKED";
-    /** Invalid delegation data */
-    readonly INVALID_DELEGATION: "INVALID_DELEGATION";
-    /** Key already registered */
-    readonly KEY_EXISTS: "KEY_EXISTS";
-};
-export type CapabilityKeyRegistryErrorCode = (typeof CapabilityKeyRegistryErrorCodes)[keyof typeof CapabilityKeyRegistryErrorCodes];
-/**
- * Stored delegation with chain information.
- */
-export interface StoredDelegationChain {
-    /** The delegation itself */
-    delegation: Delegation;
-    /** Parent delegation CID if this is a sub-delegation */
-    parentCid?: string;
-    /** Key ID used to sign/exercise this delegation */
-    keyId: string;
-    /** When this was stored */
-    storedAt: Date;
-}
-/**
- * Interface for the CapabilityKeyRegistry.
- *
- * Tracks keys and their capabilities for automatic key selection.
- */
-export interface ICapabilityKeyRegistry {
-    /**
-     * Register a key with its associated delegations.
-     *
-     * @param key - Key information
-     * @param delegations - Delegations granted to this key
-     */
-    registerKey(key: KeyInfo, delegations: Delegation[]): void;
-    /**
-     * Remove a key and all its associated delegations.
-     *
-     * @param keyId - The key ID to remove
-     */
-    removeKey(keyId: string): void;
-    /**
-     * Get a key that can exercise the specified capability.
-     *
-     * Uses the key selection algorithm:
-     * 1. Filter keys that have the required capability
-     * 2. Check delegation validity (not expired, not revoked)
-     * 3. Sort by priority (session=0, main=1, ingested=2)
-     * 4. Return highest priority valid key
-     *
-     * @param resource - Resource URI (e.g., "tinycloud://space-id/kv/my-data")
-     * @param action - Action to perform (e.g., "tinycloud.kv/get")
-     * @returns The best matching key, or null if none available
-     */
-    getKeyForCapability(resource: string, action: string): KeyInfo | null;
-    /**
-     * Get all registered capabilities.
-     *
-     * @returns All capability entries in the registry
-     */
-    getAllCapabilities(): CapabilityEntry[];
-    /**
-     * Get all delegations for a specific key.
-     *
-     * @param keyId - The key ID
-     * @returns Array of delegations for this key
-     */
-    getDelegationsForKey(keyId: string): Delegation[];
-    /**
-     * Ingest a key and delegation from an external source (e.g., sharing link).
-     *
-     * @param key - Key information to ingest
-     * @param delegation - Delegation to associate with the key
-     * @param options - Ingestion options
-     */
-    ingestKey(key: KeyInfo, delegation: Delegation, options?: IngestOptions): void;
-    /**
-     * Check if a delegation is currently valid.
-     *
-     * @param delegation - The delegation to check
-     * @returns true if valid, false if expired or revoked
-     */
-    isDelegationValid(delegation: Delegation): boolean;
-    /**
-     * Get a key by its ID.
-     *
-     * @param keyId - The key ID
-     * @returns The key info, or undefined if not found
-     */
-    getKey(keyId: string): KeyInfo | undefined;
-    /**
-     * Get all registered keys.
-     *
-     * @returns Array of all registered keys
-     */
-    getAllKeys(): KeyInfo[];
-    /**
-     * Clear all registered keys and delegations.
-     */
-    clear(): void;
-    /**
-     * Revoke a delegation by CID.
-     *
-     * @param cid - The delegation CID to revoke
-     * @returns Result indicating success or failure
-     */
-    revokeDelegation(cid: string): Result<void, ServiceError>;
-    /**
-     * Find capabilities that match a resource path pattern.
-     *
-     * @param resourcePattern - Resource pattern (supports wildcards)
-     * @param action - Optional action filter
-     * @returns Matching capability entries
-     */
-    findCapabilities(resourcePattern: string, action?: string): CapabilityEntry[];
-}
-/**
- * CapabilityKeyRegistry - Tracks keys and their capabilities for automatic key selection.
- *
- * @example
- * ```typescript
- * const registry = new CapabilityKeyRegistry();
- *
- * // Register a session key with its delegations
- * registry.registerKey(sessionKey, [rootDelegation]);
- *
- * // Get the best key for an operation
- * const key = registry.getKeyForCapability(
- *   "tinycloud://my-space/kv/data",
- *   "tinycloud.kv/get"
- * );
- *
- * if (key) {
- *   // Use this key for the operation
- *   console.log("Using key:", key.id);
- * }
- * ```
- */
-export declare class CapabilityKeyRegistry implements ICapabilityKeyRegistry {
-    /**
-     * Registry of all keys indexed by ID.
-     */
-    private keys;
-    /**
-     * Delegation storage.
-     */
-    private store;
-    /**
-     * Register a key with its associated delegations.
-     *
-     * @param key - Key information
-     * @param delegations - Delegations granted to this key
-     */
-    registerKey(key: KeyInfo, delegations: Delegation[]): void;
-    /**
-     * Remove a key and all its associated delegations.
-     *
-     * @param keyId - The key ID to remove
-     */
-    removeKey(keyId: string): void;
-    /**
-     * Get a key that can exercise the specified capability.
-     *
-     * Key selection algorithm:
-     * 1. Filter keys that have the required capability
-     * 2. Check delegation validity (not expired, not revoked)
-     * 3. Sort by priority (session=0, main=1, ingested=2)
-     * 4. Return highest priority valid key
-     *
-     * @param resource - Resource URI
-     * @param action - Action to perform
-     * @returns The best matching key, or null if none available
-     */
-    getKeyForCapability(resource: string, action: string): KeyInfo | null;
-    /**
-     * Get all registered capabilities.
-     *
-     * @returns All capability entries in the registry
-     */
-    getAllCapabilities(): CapabilityEntry[];
-    /**
-     * Get all delegations for a specific key.
-     *
-     * @param keyId - The key ID
-     * @returns Array of delegations for this key
-     */
-    getDelegationsForKey(keyId: string): Delegation[];
-    /**
-     * Ingest a key and delegation from an external source.
-     *
-     * @param key - Key information to ingest
-     * @param delegation - Delegation to associate with the key
-     * @param options - Ingestion options
-     */
-    ingestKey(key: KeyInfo, delegation: Delegation, options?: IngestOptions): void;
-    /**
-     * Check if a delegation is currently valid.
-     *
-     * @param delegation - The delegation to check
-     * @returns true if valid, false if expired or revoked
-     */
-    isDelegationValid(delegation: Delegation): boolean;
-    /**
-     * Get a key by its ID.
-     *
-     * @param keyId - The key ID
-     * @returns The key info, or undefined if not found
-     */
-    getKey(keyId: string): KeyInfo | undefined;
-    /**
-     * Get all registered keys.
-     *
-     * @returns Array of all registered keys
-     */
-    getAllKeys(): KeyInfo[];
-    /**
-     * Clear all registered keys and delegations.
-     */
-    clear(): void;
-    /**
-     * Revoke a delegation by CID.
-     *
-     * @param cid - The delegation CID to revoke
-     * @returns Result indicating success or failure
-     */
-    revokeDelegation(cid: string): Result<void, ServiceError>;
-    /**
-     * Find capabilities that match a resource path pattern.
-     *
-     * @param resourcePattern - Resource pattern (supports wildcards)
-     * @param action - Optional action filter
-     * @returns Matching capability entries
-     */
-    findCapabilities(resourcePattern: string, action?: string): CapabilityEntry[];
-    /**
-     * Add a delegation to the store.
-     *
-     * @param key - The key associated with this delegation
-     * @param delegation - The delegation to add
-     */
-    private addDelegation;
-    /**
-     * Create a capability key for indexing.
-     *
-     * @param resource - Resource path
-     * @param action - Action
-     * @returns Combined key string
-     */
-    private makeCapabilityKey;
-    /**
-     * Find capability entries that match a resource and action.
-     *
-     * @param resource - Resource to match
-     * @param action - Action to match
-     * @returns Matching entries
-     */
-    private findMatchingEntries;
-    /**
-     * Check if an action pattern matches a specific action.
-     *
-     * @param pattern - Action pattern (may include wildcard like "tinycloud.kv/*")
-     * @param action - Specific action to check
-     * @returns true if pattern matches action
-     */
-    private actionMatches;
-    /**
-     * Check if a resource matches a pattern.
-     *
-     * Patterns support:
-     * - Exact match: "/kv/data" matches "/kv/data"
-     * - Wildcard suffix: "/kv/*" matches "/kv/anything"
-     * - Double wildcard: "/kv/**" matches "/kv/any/nested/path"
-     *
-     * @param resource - The specific resource being accessed
-     * @param pattern - The pattern from the delegation
-     * @returns true if resource matches pattern
-     */
-    private resourceMatchesPattern;
-    /**
-     * Check if a specific resource matches a resource pattern for searching.
-     *
-     * @param entryResource - The resource from a capability entry
-     * @param searchPattern - The pattern to search for
-     * @returns true if entry resource matches search pattern
-     */
-    private matchesResourcePattern;
-}
-/**
- * Create a new CapabilityKeyRegistry instance.
- *
- * @returns A new registry instance
- */
-export declare function createCapabilityKeyRegistry(): ICapabilityKeyRegistry;
-//# sourceMappingURL=CapabilityKeyRegistry.d.ts.map

package/dist/authorization/CapabilityKeyRegistry.d.ts.map

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