@vess-id/ai-identity 0.0.0-dev-20260902121045

package/dist/identity/device-enroll-manager.d.ts

@@ -0,0 +1,117 @@
+/**
+ * Device Enrollment Manager
+ *
+ * Handles the device code flow for registering a User Root DID
+ * without requiring an API key. Supports two modes:
+ *
+ * Client-generated (local mode):
+ * 1. Client calls startDeviceEnrollment() with rootDid + publicKeyJwk
+ * 2. Client presents user_code and verification_url to the user
+ * 3. User approves in browser
+ * 4. Client polls until approved, receives device_session_token
+ *
+ * Server-generated (remote mode):
+ * 1. Client calls startServerSideEnrollment() with clientInfo only
+ * 2. Server returns user_code + verification_url (DID generated on approval)
+ * 3. User approves in browser
+ * 4. Client polls until approved, receives rootDid + device_session_token
+ */
+export interface DeviceEnrollStartParams {
+    rootDid: string;
+    publicKeyJwk: {
+        kty: string;
+        crv: string;
+        x: string;
+        y?: string;
+        use?: string;
+        alg?: string;
+    };
+    clientInfo?: {
+        deviceName?: string;
+        os?: string;
+        appVersion?: string;
+        hostname?: string;
+        [key: string]: any;
+    };
+    purpose?: string;
+}
+export interface DeviceEnrollServerSideParams {
+    clientInfo?: {
+        deviceName?: string;
+        os?: string;
+        appVersion?: string;
+        hostname?: string;
+        [key: string]: any;
+    };
+    purpose?: string;
+}
+export interface DeviceEnrollStartResult {
+    requestId: string;
+    userCode: string;
+    verificationUrl: string;
+    expiresAt: string;
+}
+export interface DeviceEnrollPollResult {
+    status: 'pending' | 'approved' | 'expired' | 'denied';
+    deviceSessionToken?: string;
+    expiresAt?: string;
+    rootDid?: string;
+}
+export declare class DeviceEnrollManager {
+    private baseUrl;
+    constructor(baseUrl: string);
+    /**
+     * Build common headers for all API requests.
+     * Includes User-Agent and ngrok-skip-browser-warning to avoid
+     * ngrok free-tier interstitial pages blocking programmatic access.
+     */
+    private buildHeaders;
+    /**
+     * Start the device enrollment flow.
+     * Sends the root DID public key to the Gateway and gets a user code.
+     *
+     * @param params - Root DID public info and client metadata
+     * @returns Request ID, user code, and verification URL
+     */
+    startDeviceEnrollment(params: DeviceEnrollStartParams): Promise<DeviceEnrollStartResult>;
+    /**
+     * Start the device enrollment flow with server-side DID generation.
+     * The server generates the real key pair on approval (not at start time).
+     * Use this for remote/cloud-managed mode.
+     *
+     * @param params - Client metadata (no DID or key needed)
+     * @returns Request ID, user code, and verification URL
+     */
+    startServerSideEnrollment(params: DeviceEnrollServerSideParams): Promise<DeviceEnrollStartResult>;
+    /**
+     * Poll for enrollment status.
+     * Call this periodically after startDeviceEnrollment() to check if
+     * the user has approved the enrollment in the web UI.
+     *
+     * @param requestId - The request ID from startDeviceEnrollment()
+     * @returns Current status and token if approved
+     */
+    pollDeviceEnrollment(requestId: string): Promise<DeviceEnrollPollResult>;
+    /**
+     * Convenience method: Start enrollment and poll until completion.
+     * Returns the final result (approved, expired, or denied).
+     *
+     * @param params - Enrollment parameters (client-generated mode)
+     * @param onUserCode - Callback when user code is available (present to user)
+     * @param pollIntervalMs - Polling interval in ms (default: 3000)
+     * @param maxPolls - Maximum number of poll attempts (default: 120)
+     */
+    enrollAndWait(params: DeviceEnrollStartParams, onUserCode: (info: DeviceEnrollStartResult) => void, pollIntervalMs?: number, maxPolls?: number): Promise<DeviceEnrollPollResult>;
+    /**
+     * Convenience method: Start server-side enrollment and poll until completion.
+     * Returns the final result including the server-generated rootDid on approval.
+     *
+     * @param params - Client metadata (server-generated mode)
+     * @param onUserCode - Callback when user code is available (present to user)
+     * @param pollIntervalMs - Polling interval in ms (default: 3000)
+     * @param maxPolls - Maximum number of poll attempts (default: 120)
+     */
+    enrollServerSideAndWait(params: DeviceEnrollServerSideParams, onUserCode: (info: DeviceEnrollStartResult) => void, pollIntervalMs?: number, maxPolls?: number): Promise<DeviceEnrollPollResult>;
+    private pollUntilComplete;
+}
+//# sourceMappingURL=device-enroll-manager.d.ts.map

package/dist/identity/device-enroll-manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"device-enroll-manager.d.ts","sourceRoot":"","sources":["../../src/identity/device-enroll-manager.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,MAAM,WAAW,uBAAuB;IACtC,OAAO,EAAE,MAAM,CAAA;IACf,YAAY,EAAE;QACZ,GAAG,EAAE,MAAM,CAAA;QACX,GAAG,EAAE,MAAM,CAAA;QACX,CAAC,EAAE,MAAM,CAAA;QACT,CAAC,CAAC,EAAE,MAAM,CAAA;QACV,GAAG,CAAC,EAAE,MAAM,CAAA;QACZ,GAAG,CAAC,EAAE,MAAM,CAAA;KACb,CAAA;IACD,UAAU,CAAC,EAAE;QACX,UAAU,CAAC,EAAE,MAAM,CAAA;QACnB,EAAE,CAAC,EAAE,MAAM,CAAA;QACX,UAAU,CAAC,EAAE,MAAM,CAAA;QACnB,QAAQ,CAAC,EAAE,MAAM,CAAA;QACjB,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,CAAA;KACnB,CAAA;IACD,OAAO,CAAC,EAAE,MAAM,CAAA;CACjB;AAED,MAAM,WAAW,4BAA4B;IAC3C,UAAU,CAAC,EAAE;QACX,UAAU,CAAC,EAAE,MAAM,CAAA;QACnB,EAAE,CAAC,EAAE,MAAM,CAAA;QACX,UAAU,CAAC,EAAE,MAAM,CAAA;QACnB,QAAQ,CAAC,EAAE,MAAM,CAAA;QACjB,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,CAAA;KACnB,CAAA;IACD,OAAO,CAAC,EAAE,MAAM,CAAA;CACjB;AAED,MAAM,WAAW,uBAAuB;IACtC,SAAS,EAAE,MAAM,CAAA;IACjB,QAAQ,EAAE,MAAM,CAAA;IAChB,eAAe,EAAE,MAAM,CAAA;IACvB,SAAS,EAAE,MAAM,CAAA;CAClB;AAED,MAAM,WAAW,sBAAsB;IACrC,MAAM,EAAE,SAAS,GAAG,UAAU,GAAG,SAAS,GAAG,QAAQ,CAAA;IACrD,kBAAkB,CAAC,EAAE,MAAM,CAAA;IAC3B,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,OAAO,CAAC,EAAE,MAAM,CAAA;CACjB;AAED,qBAAa,mBAAmB;IAC9B,OAAO,CAAC,OAAO,CAAQ;gBAEX,OAAO,EAAE,MAAM;IAI3B;;;;OAIG;IACH,OAAO,CAAC,YAAY;IAQpB;;;;;;OAMG;IACG,qBAAqB,CACzB,MAAM,EAAE,uBAAuB,GAC9B,OAAO,CAAC,uBAAuB,CAAC;IA2BnC;;;;;;;OAOG;IACG,yBAAyB,CAC7B,MAAM,EAAE,4BAA4B,GACnC,OAAO,CAAC,uBAAuB,CAAC;IA0BnC;;;;;;;OAOG;IACG,oBAAoB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,sBAAsB,CAAC;IAsB9E;;;;;;;;OAQG;IACG,aAAa,CACjB,MAAM,EAAE,uBAAuB,EAC/B,UAAU,EAAE,CAAC,IAAI,EAAE,uBAAuB,KAAK,IAAI,EACnD,cAAc,GAAE,MAAa,EAC7B,QAAQ,GAAE,MAAY,GACrB,OAAO,CAAC,sBAAsB,CAAC;IAKlC;;;;;;;;OAQG;IACG,uBAAuB,CAC3B,MAAM,EAAE,4BAA4B,EACpC,UAAU,EAAE,CAAC,IAAI,EAAE,uBAAuB,KAAK,IAAI,EACnD,cAAc,GAAE,MAAa,EAC7B,QAAQ,GAAE,MAAY,GACrB,OAAO,CAAC,sBAAsB,CAAC;YAKpB,iBAAiB;CAoBhC"}

package/dist/identity/user-identity-manager.d.ts

@@ -0,0 +1,123 @@
+import { KeyManager } from '../did/key-manager';
+import { DIDDocument } from '../types';
+export interface UserIdentityManagerOptions {
+    /**
+     * Directory holding `user-did.txt`, the single file naming the DID this
+     * installation issues VCs as.
+     *
+     * 🔴 Omit this and the default stays exactly what it has always been —
+     * `~/.vess-aidentity/`. Note this is the config root itself, NOT a
+     * subdirectory: unlike `AgentDIDManager`, which owns the whole
+     * `agent-dids/` subtree, this manager owns one fixed filename inside a
+     * directory it shares with `keys/`, `agent-dids/` and `vc-cache.json`.
+     * Changing the default would orphan the existing user identity, and every
+     * VC already issued names that DID as its issuer.
+     *
+     * Supply it for either of two reasons:
+     *
+     * - **Tenant isolation.** With the path hard-coded to `os.homedir()`, one
+     *   process serving several tenants has a single user DID for all of them.
+     *   Worse than the agent case: agent IDs at least namespace the files, while
+     *   the user DID is one fixed filename, so the last tenant to call
+     *   `createUserDID` silently overwrites everyone else's issuer identity.
+     *
+     * - **Test isolation.** Tests could not otherwise steer this path away from
+     *   the developer's real home. Under jest, `process.env.HOME = x` does not
+     *   help: jest-environment-node replaces `process.env` with a plain object
+     *   behind a Proxy, so the assignment never reaches `setenv(3)`, while
+     *   `os.homedir()` goes through libuv to `getenv("HOME")` and reads the real
+     *   environ. Both reads and writes therefore escape to the real home and the
+     *   suite stays green while clobbering the developer's own user DID.
+     */
+    mappingDir?: string;
+}
+/**
+ * User Identity Manager
+ * Manages DID generation and lifecycle for Users (Issuers) specifically
+ * Separate from Agent management to avoid confusion
+ */
+export declare class UserIdentityManager {
+    private keyManager;
+    private currentUserDID;
+    private readonly mappingDirOverride?;
+    constructor(keyManager?: KeyManager, options?: UserIdentityManagerOptions);
+    /**
+     * 🔴 The one place the user-DID directory is derived.
+     *
+     * It used to be derived independently in `saveUserDID` / `loadUserDID` /
+     * `clearUserDID`. That is the same shape `AgentDIDManager` was in before
+     * PR #1442, where the copies had actually drifted — load and delete looked
+     * at `~/.vess/` while save wrote to `~/.vess-aidentity/`. Nothing caught it
+     * in-process because the in-memory field answered first; across processes
+     * the load always missed. Here `currentUserDID` plays that same masking
+     * role, so a drift would likewise only show up after a restart.
+     *
+     * The default is the config root `~/.vess-aidentity/` and must stay that
+     * way — see the note on `UserIdentityManagerOptions.mappingDir`.
+     */
+    private userDidDir;
+    /**
+     * Absolute path of the file holding the user DID.
+     *
+     * Derived from `userDidDir()` so the filename cannot drift either — the
+     * three call sites used to spell `'user-did.txt'` out separately as well.
+     */
+    private userDidFile;
+    /**
+     * Get or create current user DID
+     * This represents the user who will be the issuer of VCs
+     */
+    getCurrentUserDID(): Promise<string>;
+    /**
+     * Create a new user DID (for issuing VCs)
+     */
+    createUserDID(): Promise<string>;
+    /**
+     * Get user's key pair
+     */
+    getUserKeyPair(): Promise<any>;
+    /**
+     * Resolve user DID to DID Document
+     */
+    resolveUserDID(did?: string): Promise<DIDDocument>;
+    /**
+     * Export user identity for backup
+     */
+    exportUserIdentity(): Promise<{
+        did: string;
+        privateKey: any;
+        didDocument: DIDDocument;
+    }>;
+    /**
+     * Import user identity from backup
+     */
+    importUserIdentity(backup: {
+        did: string;
+        privateKey: any;
+    }): Promise<void>;
+    /**
+     * Reset user identity (create new DID)
+     */
+    resetUserIdentity(): Promise<string>;
+    /**
+     * Resolve did:jwk locally
+     */
+    private resolveDidJwkLocally;
+    /**
+     * Create DID Document
+     */
+    private createDidDocument;
+    /**
+     * Save current user DID to persistent storage
+     */
+    private saveUserDID;
+    /**
+     * Load current user DID from persistent storage
+     */
+    private loadUserDID;
+    /**
+     * Clear saved user DID
+     */
+    private clearUserDID;
+}
+//# sourceMappingURL=user-identity-manager.d.ts.map

package/dist/identity/user-identity-manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"user-identity-manager.d.ts","sourceRoot":"","sources":["../../src/identity/user-identity-manager.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAA;AAG/C,OAAO,EAAE,WAAW,EAAE,MAAM,UAAU,CAAA;AAEtC,MAAM,WAAW,0BAA0B;IACzC;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2BG;IACH,UAAU,CAAC,EAAE,MAAM,CAAA;CACpB;AAED;;;;GAIG;AACH,qBAAa,mBAAmB;IAC9B,OAAO,CAAC,UAAU,CAAY;IAC9B,OAAO,CAAC,cAAc,CAAsB;IAC5C,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAAC,CAAQ;gBAEhC,UAAU,CAAC,EAAE,UAAU,EAAE,OAAO,CAAC,EAAE,0BAA0B;IAKzE;;;;;;;;;;;;;OAaG;YACW,UAAU;IASxB;;;;;OAKG;YACW,WAAW;IAMzB;;;OAGG;IACG,iBAAiB,IAAI,OAAO,CAAC,MAAM,CAAC;IAgB1C;;OAEG;IACG,aAAa,IAAI,OAAO,CAAC,MAAM,CAAC;IAiBtC;;OAEG;IACG,cAAc,IAAI,OAAO,CAAC,GAAG,CAAC;IAcpC;;OAEG;IACG,cAAc,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC;IAUxD;;OAEG;IACG,kBAAkB,IAAI,OAAO,CAAC;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,GAAG,CAAC;QAAC,WAAW,EAAE,WAAW,CAAA;KAAE,CAAC;IAY/F;;OAEG;IACG,kBAAkB,CAAC,MAAM,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,GAAG,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IASjF;;OAEG;IACG,iBAAiB,IAAI,OAAO,CAAC,MAAM,CAAC;IAW1C;;OAEG;IACH,OAAO,CAAC,oBAAoB;IAK5B;;OAEG;IACH,OAAO,CAAC,iBAAiB;IAqBzB;;OAEG;YACW,WAAW;IAUzB;;OAEG;YACW,WAAW;IAazB;;OAEG;YACW,YAAY;CAY3B"}

package/dist/identity/user-key-pair-manager.d.ts

@@ -0,0 +1,22 @@
+import type { JWK } from 'jose';
+export interface KeyPairGenerationResult {
+    did: string;
+    publicKey: JWK;
+    privateKey: JWK;
+}
+/**
+ * Manages key pair generation for remote user issuer.
+ * Generates ES256 key pairs and creates did:jwk DIDs.
+ */
+export declare class UserKeyPairManager {
+    /**
+     * Generate a new key pair and create a did:jwk DID
+     */
+    generateKeyPair(): Promise<KeyPairGenerationResult>;
+    /**
+     * Extract public key info from a did:jwk DID
+     * @throws Error if the DID is not in did:jwk format
+     */
+    extractPublicKeyInfo(did: string): JWK;
+}
+//# sourceMappingURL=user-key-pair-manager.d.ts.map

package/dist/identity/user-key-pair-manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"user-key-pair-manager.d.ts","sourceRoot":"","sources":["../../src/identity/user-key-pair-manager.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,MAAM,CAAA;AAE/B,MAAM,WAAW,uBAAuB;IACtC,GAAG,EAAE,MAAM,CAAA;IACX,SAAS,EAAE,GAAG,CAAA;IACd,UAAU,EAAE,GAAG,CAAA;CAChB;AAED;;;GAGG;AACH,qBAAa,kBAAkB;IAC7B;;OAEG;IACG,eAAe,IAAI,OAAO,CAAC,uBAAuB,CAAC;IAWzD;;;OAGG;IACH,oBAAoB,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG;CAMvC"}