@vess-id/ai-identity 0.10.0 → 0.12.0

package/dist/index.d.mts

@@ -4,6 +4,31 @@ import Ajv from 'ajv';
 import { SDJwtVcInstance } from '@sd-jwt/sd-jwt-vc';
 import { DisclosureFrame } from '@sd-jwt/types';
 
+interface AIdentityConfig {
+    didApi?: {
+        baseUrl: string;
+        apiKey?: string;
+        bearerToken?: string;
+    };
+    issuerApi?: {
+        baseUrl: string;
+        apiKey?: string;
+        bearerToken?: string;
+    };
+    verifierApi?: {
+        baseUrl: string;
+        apiKey?: string;
+        bearerToken?: string;
+    };
+    proxyApi?: {
+        baseUrl: string;
+    };
+    storage?: {
+        keyStorePath?: string;
+    };
+}
+declare function configure(config: AIdentityConfig): void;
+
 interface DIDDocument {
     '@context': string | string[];
     id: string;
@@ -2803,145 +2828,6 @@ declare class KeyManager {
     private decrypt;
 }
 
-declare class VPManager {
-    private keyManager;
-    constructor(keyManager?: KeyManager);
-    /**
-     * Create a SD-JWT presentation using the present() method
-     * This properly binds the holder's key to the SD-JWT VC
-     */
-    create(vcs: string[], // Array of SD-JWT VC strings
-    options: {
-        holderDid: string;
-        challenge: string;
-        domain: string;
-        purpose?: string;
-    }): Promise<string>;
-    /**
-     * Verify a Verifiable Presentation
-     */
-    verify(vpJwt: string, options: {
-        expectedChallenge: string;
-        expectedDomain: string;
-        expectedHolder?: string;
-    }): Promise<VerifiablePresentation>;
-    /**
-     * Create a VP request
-     */
-    createRequest(domain: string, query?: {
-        type?: string;
-        credentialQuery?: any;
-    }): VPRequest;
-    /**
-     * Submit VP to a verifier
-     */
-    submit(vpJwt: string, verifierEndpoint: string): Promise<{
-        verified: boolean;
-        result?: any;
-    }>;
-}
-
-/**
- * NOTE: MemoryManager is currently DORMANT (as of 2026-03-29).
- * The API memory endpoints exist but are not actively called in production.
- * The server-side implementation (InMemoryProvider) is volatile and not shared across instances.
- * Do not rely on this in production until a persistent backend is introduced.
- */
-interface MemoryDocument {
-    id: string;
-    namespace: string;
-    content: string;
-    metadata?: Record<string, any>;
-    embedding?: number[];
-    createdAt: string;
-    updatedAt: string;
-}
-interface MemoryQuery {
-    query: string;
-    namespace?: string;
-    limit?: number;
-    filter?: Record<string, any>;
-    includeEmbedding?: boolean;
-}
-interface MemoryQueryResult {
-    documents: MemoryDocument[];
-    scores?: number[];
-    total: number;
-}
-declare class MemoryManager {
-    private vpManager;
-    private proxyApiUrl;
-    constructor(vpManager?: VPManager);
-    /**
-     * Write a document to memory
-     */
-    write(content: string, options: {
-        namespace: string;
-        metadata?: Record<string, any>;
-        vcs: string[];
-        holderDid: string;
-    }): Promise<MemoryDocument>;
-    /**
-     * Query memory with vector search
-     */
-    query(query: string, options: {
-        namespace?: string;
-        limit?: number;
-        filter?: Record<string, any>;
-        vcs: string[];
-        holderDid: string;
-    }): Promise<MemoryQueryResult>;
-    /**
-     * Delete a document from memory
-     */
-    delete(documentId: string, options: {
-        namespace: string;
-        vcs: string[];
-        holderDid: string;
-    }): Promise<void>;
-    /**
-     * List documents in a namespace
-     */
-    list(options: {
-        namespace: string;
-        limit?: number;
-        offset?: number;
-        vcs: string[];
-        holderDid: string;
-    }): Promise<MemoryQueryResult>;
-    /**
-     * Check if VCs authorize memory access
-     */
-    checkAuthorization(vcs: string[], action: 'read' | 'write' | 'delete', resource: string): Promise<boolean>;
-    private matchResource;
-    private generateChallenge;
-}
-
-interface AIdentityConfig {
-    didApi?: {
-        baseUrl: string;
-        apiKey?: string;
-        bearerToken?: string;
-    };
-    issuerApi?: {
-        baseUrl: string;
-        apiKey?: string;
-        bearerToken?: string;
-    };
-    verifierApi?: {
-        baseUrl: string;
-        apiKey?: string;
-        bearerToken?: string;
-    };
-    proxyApi?: {
-        baseUrl: string;
-    };
-    storage?: {
-        keyStorePath?: string;
-    };
-}
-declare function configure(config: AIdentityConfig): void;
-
 declare class AgentManager {
     private keyManager;
     private agentDIDManager;
@@ -3110,6 +2996,44 @@ declare class VCManager {
     private calculateExpirationDate;
 }
 
+declare class VPManager {
+    private keyManager;
+    constructor(keyManager?: KeyManager);
+    /**
+     * Create a SD-JWT presentation using the present() method
+     * This properly binds the holder's key to the SD-JWT VC
+     */
+    create(vcs: string[], // Array of SD-JWT VC strings
+    options: {
+        holderDid: string;
+        challenge: string;
+        domain: string;
+        purpose?: string;
+    }): Promise<string>;
+    /**
+     * Verify a Verifiable Presentation
+     */
+    verify(vpJwt: string, options: {
+        expectedChallenge: string;
+        expectedDomain: string;
+        expectedHolder?: string;
+    }): Promise<VerifiablePresentation>;
+    /**
+     * Create a VP request
+     */
+    createRequest(domain: string, query?: {
+        type?: string;
+        credentialQuery?: any;
+    }): VPRequest;
+    /**
+     * Submit VP to a verifier
+     */
+    submit(vpJwt: string, verifierEndpoint: string): Promise<{
+        verified: boolean;
+        result?: any;
+    }>;
+}
+
 interface ToolDefinition {
     name: string;
     description: string;
@@ -3296,7 +3220,6 @@ declare class AIdentityClient {
     readonly vc: VCManager;
     readonly vp: VPManager;
     readonly tool: ToolManager;
-    readonly memory: MemoryManager;
     readonly grant: GrantManager;
     private keyManager;
     private currentAgent?;
@@ -3342,18 +3265,6 @@ declare class AIdentityClient {
      * Invoke a tool with automatic VP creation
      */
     invokeTool<T = any>(tool: string, action: string, params: Record<string, any>, vcs: string[]): Promise<ConnectorResponse<T>>;
-    /**
-     * Write to memory with automatic VP creation
-     */
-    writeMemory(content: string, namespace: string, vcs: string[], metadata?: Record<string, any>): Promise<MemoryDocument>;
-    /**
-     * Query memory with automatic VP creation
-     */
-    queryMemory(query: string, vcs: string[], options?: {
-        namespace?: string;
-        limit?: number;
-        filter?: Record<string, any>;
-    }): Promise<MemoryQueryResult>;
 }
 declare function getClient(config?: AIdentityConfig, password?: string): AIdentityClient;
 
@@ -3580,6 +3491,95 @@ declare class APIVCManager {
     issueAdminCredential(agentDid: string, scope: 'project' | 'global', projectId: string | undefined, issuerDid: string, expirationHours?: number): Promise<IssueSDJWTVCResult>;
 }
 
+/**
+ * Single source of truth for Key Binding JWT (KB-JWT) issuance shared across
+ * the AIdentity stack. Four production code paths build KB-JWTs and they
+ * MUST stay byte-for-byte equivalent so a presentation built on one side is
+ * accepted by the verifier on the other:
+ *
+ *   - SDK clients via `VPManager.create()` (this package)
+ *   - API service via `packages/api/src/vp/vp-creation.service.ts`
+ *   - Remote MCP via `packages/remote-mcp/src/services/vp-creation.service.ts`
+ *   - agentd (`@vess-id/vess`) via `VPBuilder.buildVP()`
+ *     (`packages/agentd/src/wallet/vp-builder.ts`)
+ *
+ * Historically each path had its own copy of this logic. PR #391 (the
+ * commit that made `exp` REQUIRED on the verifier side) updated only two of
+ * the three issuer paths known at the time; the SDK was missed and every
+ * SDK-built VP started failing at verification time. The follow-up
+ * consolidation (commit 02b169aa) brought the SDK in line, but agentd —
+ * which had its own KB-JWT literal in `wallet/vp-builder.ts` — was not
+ * recognized as a fourth issuer. Staging then rejected every VP from
+ * `@vess-id/vess` agentd alpha builds with `KB-JWT missing exp` until the
+ * agentd hotfix (this commit's cohort) wired its VPBuilder through
+ * `buildKbJwtPayload()`. This module exists so that a future verifier
+ * change cannot drift from the issuer side: any update lands in one place
+ * and all four paths inherit it.
+ */
+/**
+ * Default KB-JWT lifetime in seconds. Mirrors the cap enforced by the API's
+ * `KeyBindingVerifierService.MAX_KB_JWT_LIFETIME_SECONDS` (also 300).
+ *
+ * The KB-JWT `exp` is the smaller of:
+ *   - `iat + KB_JWT_DEFAULT_LIFETIME_SECONDS`
+ *   - the parent VC's `exp` (so the bearer's freshness window cannot outlive
+ *     the underlying credential's validity, which is itself bounded by
+ *     `grant.expiresAt` at issuance time).
+ */
+declare const KB_JWT_DEFAULT_LIFETIME_SECONDS = 300;
+interface KbJwtPayload {
+    iss: string;
+    aud: string;
+    nonce: string;
+    iat: number;
+    exp: number;
+}
+interface BuildKbJwtPayloadArgs {
+    /** Holder DID — becomes the KB-JWT `iss` claim. */
+    holderDid: string;
+    /** Verifier audience (URL or hostname). Will be normalized via {@link normalizeDomain}. */
+    audience: string;
+    /** Verifier-supplied nonce / challenge. */
+    nonce: string;
+    /** The parent SD-JWT VC string. Its `exp` (if any) caps the KB-JWT lifetime. */
+    vcCredential: string;
+}
+interface BuildKbJwtPayloadDeps {
+    /** Returns the current time in milliseconds. Defaults to `Date.now`. */
+    now?: () => number;
+}
+/**
+ * Build a Key Binding JWT payload for an SD-JWT VC presentation.
+ *
+ * Throws when the parent VC is already expired (`vc.exp <= now`). The error
+ * message intentionally contains the substring `"VC has expired"` so that
+ * downstream catchers (notably remote-mcp's `isCredentialInvalidError`) can
+ * detect a stale-credential condition and trigger a re-approval flow rather
+ * than surface an opaque issuance failure to the user.
+ */
+declare function buildKbJwtPayload(args: BuildKbJwtPayloadArgs, deps?: BuildKbJwtPayloadDeps): KbJwtPayload;
+/**
+ * Best-effort read of the VC's `exp` claim from the SD-JWT outer payload.
+ * Returns undefined when the VC is malformed, missing exp, or the field is
+ * not a number — callers fall back to {@link KB_JWT_DEFAULT_LIFETIME_SECONDS}
+ * in that case so issuance does not break for VCs without an explicit expiry.
+ */
+declare function readVcExpSeconds(sdJwtVc: string): number | undefined;
+/**
+ * Normalize a domain string for consistent use as a JWT `aud` claim.
+ *
+ * The API verifier compares the KB-JWT `aud` against the expected domain by
+ * exact string match, so issuer and verifier must agree on the canonical
+ * form. We delegate to the URL parser, which strips paths and lowercases
+ * the host, then return the resulting `origin`.
+ *
+ * Inputs without a scheme are assumed to be hostnames; `localhost` (with or
+ * without a port) defaults to `http://`, everything else to `https://`. If
+ * URL parsing fails, the input is returned unchanged so a caller can still
+ * detect the mismatch downstream rather than silently swallowing a typo.
+ */
+declare function normalizeDomain(domain: string): string;
+
 interface DisclosureFields {
     selectiveFields: string[];
     mandatoryFields: string[];
@@ -4249,6 +4249,9 @@ declare const ACTION_REGISTRY: {
                 subject?: undefined;
                 cc?: undefined;
                 bcc?: undefined;
+                threadId?: undefined;
+                inReplyTo?: undefined;
+                references?: undefined;
                 messageIds?: undefined;
                 calendarId?: undefined;
                 timeMin?: undefined;
@@ -4342,6 +4345,9 @@ declare const ACTION_REGISTRY: {
                 subject?: undefined;
                 cc?: undefined;
                 bcc?: undefined;
+                threadId?: undefined;
+                inReplyTo?: undefined;
+                references?: undefined;
                 messageIds?: undefined;
                 calendarId?: undefined;
                 timeMin?: undefined;
@@ -4438,6 +4444,9 @@ declare const ACTION_REGISTRY: {
                 subject?: undefined;
                 cc?: undefined;
                 bcc?: undefined;
+                threadId?: undefined;
+                inReplyTo?: undefined;
+                references?: undefined;
                 messageIds?: undefined;
                 calendarId?: undefined;
                 timeMin?: undefined;
@@ -4544,6 +4553,9 @@ declare const ACTION_REGISTRY: {
                 subject?: undefined;
                 cc?: undefined;
                 bcc?: undefined;
+                threadId?: undefined;
+                inReplyTo?: undefined;
+                references?: undefined;
                 messageIds?: undefined;
                 calendarId?: undefined;
                 timeMin?: undefined;
@@ -4647,6 +4659,9 @@ declare const ACTION_REGISTRY: {
                 subject?: undefined;
                 cc?: undefined;
                 bcc?: undefined;
+                threadId?: undefined;
+                inReplyTo?: undefined;
+                references?: undefined;
                 messageIds?: undefined;
                 calendarId?: undefined;
                 timeMin?: undefined;
@@ -4747,6 +4762,9 @@ declare const ACTION_REGISTRY: {
                 subject?: undefined;
                 cc?: undefined;
                 bcc?: undefined;
+                threadId?: undefined;
+                inReplyTo?: undefined;
+                references?: undefined;
                 messageIds?: undefined;
                 calendarId?: undefined;
                 timeMin?: undefined;
@@ -4850,6 +4868,9 @@ declare const ACTION_REGISTRY: {
                 subject?: undefined;
                 cc?: undefined;
                 bcc?: undefined;
+                threadId?: undefined;
+                inReplyTo?: undefined;
+                references?: undefined;
                 messageIds?: undefined;
                 calendarId?: undefined;
                 timeMin?: undefined;
@@ -4949,6 +4970,9 @@ declare const ACTION_REGISTRY: {
                 subject?: undefined;
                 cc?: undefined;
                 bcc?: undefined;
+                threadId?: undefined;
+                inReplyTo?: undefined;
+                references?: undefined;
                 messageIds?: undefined;
                 calendarId?: undefined;
                 timeMin?: undefined;
@@ -5058,6 +5082,9 @@ declare const ACTION_REGISTRY: {
                 subject?: undefined;
                 cc?: undefined;
                 bcc?: undefined;
+                threadId?: undefined;
+                inReplyTo?: undefined;
+                references?: undefined;
                 messageIds?: undefined;
                 calendarId?: undefined;
                 timeMin?: undefined;
@@ -5170,6 +5197,9 @@ declare const ACTION_REGISTRY: {
                 subject?: undefined;
                 cc?: undefined;
                 bcc?: undefined;
+                threadId?: undefined;
+                inReplyTo?: undefined;
+                references?: undefined;
                 messageIds?: undefined;
                 calendarId?: undefined;
                 timeMin?: undefined;
@@ -5266,6 +5296,9 @@ declare const ACTION_REGISTRY: {
                 subject?: undefined;
                 cc?: undefined;
                 bcc?: undefined;
+                threadId?: undefined;
+                inReplyTo?: undefined;
+                references?: undefined;
                 messageIds?: undefined;
                 calendarId?: undefined;
                 timeMin?: undefined;
@@ -5381,6 +5414,9 @@ declare const ACTION_REGISTRY: {
                 subject?: undefined;
                 cc?: undefined;
                 bcc?: undefined;
+                threadId?: undefined;
+                inReplyTo?: undefined;
+                references?: undefined;
                 messageIds?: undefined;
                 calendarId?: undefined;
                 timeMin?: undefined;
@@ -5482,6 +5518,9 @@ declare const ACTION_REGISTRY: {
                 subject?: undefined;
                 cc?: undefined;
                 bcc?: undefined;
+                threadId?: undefined;
+                inReplyTo?: undefined;
+                references?: undefined;
                 messageIds?: undefined;
                 calendarId?: undefined;
                 timeMin?: undefined;
@@ -5578,6 +5617,9 @@ declare const ACTION_REGISTRY: {
                 subject?: undefined;
                 cc?: undefined;
                 bcc?: undefined;
+                threadId?: undefined;
+                inReplyTo?: undefined;
+                references?: undefined;
                 messageIds?: undefined;
                 calendarId?: undefined;
                 timeMin?: undefined;
@@ -5659,6 +5701,15 @@ declare const ACTION_REGISTRY: {
                 bcc: {
                     type: string;
                 };
+                threadId: {
+                    type: string;
+                };
+                inReplyTo: {
+                    type: string;
+                };
+                references: {
+                    type: string;
+                };
                 channel?: undefined;
                 text?: undefined;
                 thread_ts?: undefined;
@@ -5793,6 +5844,9 @@ declare const ACTION_REGISTRY: {
                 subject?: undefined;
                 cc?: undefined;
                 bcc?: undefined;
+                threadId?: undefined;
+                inReplyTo?: undefined;
+                references?: undefined;
                 calendarId?: undefined;
                 timeMin?: undefined;
                 timeMax?: undefined;
@@ -5902,6 +5956,9 @@ declare const ACTION_REGISTRY: {
                 subject?: undefined;
                 cc?: undefined;
                 bcc?: undefined;
+                threadId?: undefined;
+                inReplyTo?: undefined;
+                references?: undefined;
                 messageIds?: undefined;
                 eventId?: undefined;
                 summary?: undefined;
@@ -6001,6 +6058,9 @@ declare const ACTION_REGISTRY: {
                 subject?: undefined;
                 cc?: undefined;
                 bcc?: undefined;
+                threadId?: undefined;
+                inReplyTo?: undefined;
+                references?: undefined;
                 messageIds?: undefined;
                 timeMin?: undefined;
                 timeMax?: undefined;
@@ -6157,6 +6217,9 @@ declare const ACTION_REGISTRY: {
                 subject?: undefined;
                 cc?: undefined;
                 bcc?: undefined;
+                threadId?: undefined;
+                inReplyTo?: undefined;
+                references?: undefined;
                 messageIds?: undefined;
                 timeMin?: undefined;
                 timeMax?: undefined;
@@ -6320,6 +6383,9 @@ declare const ACTION_REGISTRY: {
                 subject?: undefined;
                 cc?: undefined;
                 bcc?: undefined;
+                threadId?: undefined;
+                inReplyTo?: undefined;
+                references?: undefined;
                 messageIds?: undefined;
                 timeMin?: undefined;
                 timeMax?: undefined;
@@ -6421,6 +6487,9 @@ declare const ACTION_REGISTRY: {
                 subject?: undefined;
                 cc?: undefined;
                 bcc?: undefined;
+                threadId?: undefined;
+                inReplyTo?: undefined;
+                references?: undefined;
                 messageIds?: undefined;
                 timeMin?: undefined;
                 timeMax?: undefined;
@@ -6515,6 +6584,9 @@ declare const ACTION_REGISTRY: {
                 subject?: undefined;
                 cc?: undefined;
                 bcc?: undefined;
+                threadId?: undefined;
+                inReplyTo?: undefined;
+                references?: undefined;
                 messageIds?: undefined;
                 calendarId?: undefined;
                 timeMin?: undefined;
@@ -6613,6 +6685,9 @@ declare const ACTION_REGISTRY: {
                 subject?: undefined;
                 cc?: undefined;
                 bcc?: undefined;
+                threadId?: undefined;
+                inReplyTo?: undefined;
+                references?: undefined;
                 messageIds?: undefined;
                 calendarId?: undefined;
                 timeMin?: undefined;
@@ -6711,6 +6786,9 @@ declare const ACTION_REGISTRY: {
                 subject?: undefined;
                 cc?: undefined;
                 bcc?: undefined;
+                threadId?: undefined;
+                inReplyTo?: undefined;
+                references?: undefined;
                 messageIds?: undefined;
                 calendarId?: undefined;
                 timeMin?: undefined;
@@ -6812,6 +6890,9 @@ declare const ACTION_REGISTRY: {
                 subject?: undefined;
                 cc?: undefined;
                 bcc?: undefined;
+                threadId?: undefined;
+                inReplyTo?: undefined;
+                references?: undefined;
                 messageIds?: undefined;
                 calendarId?: undefined;
                 timeMin?: undefined;
@@ -6917,6 +6998,9 @@ declare const ACTION_REGISTRY: {
                 subject?: undefined;
                 cc?: undefined;
                 bcc?: undefined;
+                threadId?: undefined;
+                inReplyTo?: undefined;
+                references?: undefined;
                 messageIds?: undefined;
                 calendarId?: undefined;
                 timeMin?: undefined;
@@ -7012,6 +7096,9 @@ declare const ACTION_REGISTRY: {
                 subject?: undefined;
                 cc?: undefined;
                 bcc?: undefined;
+                threadId?: undefined;
+                inReplyTo?: undefined;
+                references?: undefined;
                 messageIds?: undefined;
                 calendarId?: undefined;
                 timeMin?: undefined;
@@ -7133,6 +7220,9 @@ declare const ACTION_REGISTRY: {
                 subject?: undefined;
                 cc?: undefined;
                 bcc?: undefined;
+                threadId?: undefined;
+                inReplyTo?: undefined;
+                references?: undefined;
                 messageIds?: undefined;
                 calendarId?: undefined;
                 timeMin?: undefined;
@@ -7244,6 +7334,9 @@ declare const ACTION_REGISTRY: {
                 subject?: undefined;
                 cc?: undefined;
                 bcc?: undefined;
+                threadId?: undefined;
+                inReplyTo?: undefined;
+                references?: undefined;
                 messageIds?: undefined;
                 calendarId?: undefined;
                 timeMin?: undefined;
@@ -7336,6 +7429,9 @@ declare const ACTION_REGISTRY: {
                 subject?: undefined;
                 cc?: undefined;
                 bcc?: undefined;
+                threadId?: undefined;
+                inReplyTo?: undefined;
+                references?: undefined;
                 messageIds?: undefined;
                 calendarId?: undefined;
                 timeMin?: undefined;
@@ -7435,6 +7531,9 @@ declare const ACTION_REGISTRY: {
                 subject?: undefined;
                 cc?: undefined;
                 bcc?: undefined;
+                threadId?: undefined;
+                inReplyTo?: undefined;
+                references?: undefined;
                 messageIds?: undefined;
                 calendarId?: undefined;
                 timeMin?: undefined;
@@ -7535,6 +7634,9 @@ declare const ACTION_REGISTRY: {
                 subject?: undefined;
                 cc?: undefined;
                 bcc?: undefined;
+                threadId?: undefined;
+                inReplyTo?: undefined;
+                references?: undefined;
                 messageIds?: undefined;
                 calendarId?: undefined;
                 timeMin?: undefined;
@@ -7641,6 +7743,9 @@ declare const ACTION_REGISTRY: {
                 subject?: undefined;
                 cc?: undefined;
                 bcc?: undefined;
+                threadId?: undefined;
+                inReplyTo?: undefined;
+                references?: undefined;
                 messageIds?: undefined;
                 calendarId?: undefined;
                 timeMin?: undefined;
@@ -7733,6 +7838,9 @@ declare const ACTION_REGISTRY: {
                 subject?: undefined;
                 cc?: undefined;
                 bcc?: undefined;
+                threadId?: undefined;
+                inReplyTo?: undefined;
+                references?: undefined;
                 messageIds?: undefined;
                 calendarId?: undefined;
                 timeMin?: undefined;
@@ -7831,6 +7939,9 @@ declare const ACTION_REGISTRY: {
                 subject?: undefined;
                 cc?: undefined;
                 bcc?: undefined;
+                threadId?: undefined;
+                inReplyTo?: undefined;
+                references?: undefined;
                 messageIds?: undefined;
                 calendarId?: undefined;
                 timeMin?: undefined;
@@ -7939,6 +8050,9 @@ declare const ACTION_REGISTRY: {
                 subject?: undefined;
                 cc?: undefined;
                 bcc?: undefined;
+                threadId?: undefined;
+                inReplyTo?: undefined;
+                references?: undefined;
                 messageIds?: undefined;
                 calendarId?: undefined;
                 timeMin?: undefined;
@@ -8121,6 +8235,39 @@ declare function getValidMcpActionNames(toolName: string): string[];
  */
 declare function normalizeMcpActionName(toolName: string, actionName: string): string;
 
+/**
+ * Cross-package constants for the reauth pipeline.
+ *
+ * These string literals are contract-level identifiers shared between:
+ *   - api (`tool-auth.service.ts`, `token-refresh.service.ts`)
+ *   - remote-mcp (`mcp-format-result.ts`)
+ *   - agentd (`gateway-client.ts`, `credential-errors.ts`, `execution-engine.ts`)
+ *
+ * Hard-coding them at each site made typo bugs silent. Centralizing here
+ * means any renames surface as a compile error on every import site.
+ */
+/**
+ * Value for `ToolInvokeResponse.metadata.action` when the api signals a
+ * revoked/expired OAuth token. Consumers branch on this to render a reauth
+ * prompt (Slack DM card, CLI authUrl, etc.) instead of treating the response
+ * as a normal error.
+ */
+declare const REAUTH_REQUIRED_ACTION: "reauth_required";
+/**
+ * Error codes emitted by agentd's `gateway-client.invokeTool` to classify
+ * failure modes for the ExecutionEngine to branch on. Kept as a const object
+ * rather than an enum so it serializes cleanly across the wire and in logs.
+ */
+declare const GATEWAY_ERROR_CODE: {
+    /** Upstream OAuth token is revoked — the user must re-auth at the SaaS provider. */
+    readonly REAUTH_REQUIRED: "REAUTH_REQUIRED";
+    /** Local VC/VP is invalid (expired, malformed, signature mismatch). Try VC reissuance. */
+    readonly CREDENTIAL_INVALID: "CREDENTIAL_INVALID";
+    /** VC allowed a different resource than the request targeted. Try a new approval. */
+    readonly RESOURCE_MISMATCH: "RESOURCE_MISMATCH";
+};
+type GatewayErrorCode = (typeof GATEWAY_ERROR_CODE)[keyof typeof GATEWAY_ERROR_CODE];
+
 interface ActionParamDisplay {
     label: string;
     value: string;
@@ -8458,6 +8605,162 @@ declare function resolveUserTier(tier: string | undefined | null): UserTier;
  */
 declare function getTierLimits(tier: string | undefined | null): TierLimits;
 
+/**
+ * P1-A14a-1 / Threat Model S4 — canonical-string + signature-header
+ * helpers for HMAC body signing of internal HTTP requests.
+ *
+ * Pure module: no NestJS, no I/O, no side effects. SDK is the
+ * single source of truth (P1-A14a-2d) — api / remote-mcp /
+ * slack-bot all import from `@vess-id/ai-identity`.
+ *
+ * Header format (Q1 = A, Stripe-style versioned):
+ *   X-Internal-Signature: v1=<keyId>:<unixSeconds>:<base64(hmac)>
+ *
+ * Canonical string (Q2 = A, no header inclusion):
+ *   ${METHOD.toUpperCase()}\n${path}\n${unixSeconds}\n${sha256Hex(rawBody)}
+ *
+ * Replay window (Q3 = A): 300 seconds — enforced by the api guard,
+ * not here. This module is responsible for *constructing* the
+ * canonical string and *parsing* the header; freshness is policy.
+ */
+declare const SIGNATURE_HEADER = "x-internal-signature";
+declare const SIGNATURE_VERSION_PREFIX = "v1=";
+/**
+ * SHA-256 hex digest of an arbitrary buffer or string. Hex (not
+ * base64) so the canonical string is URL-safe and grep-friendly in
+ * logs if a future debug session ever needs to reconstruct it
+ * server-side.
+ */
+declare function sha256Hex(input: Buffer | string): string;
+/**
+ * Build the canonical string that gets HMAC'd. The components are
+ * separated by `\n` because no legitimate input contains `\n` (the
+ * method is uppercase ASCII, the path is URL-encoded by the caller,
+ * the timestamp is digits, the body hash is hex). Using `\n` as
+ * separator avoids ambiguity that delimiters like `:` would
+ * introduce when the path contains a colon.
+ *
+ * Whitespace is NOT trimmed — input must be exactly what will land
+ * on the wire. Caller controls case and encoding.
+ */
+declare function buildCanonicalString(args: {
+    method: string;
+    path: string;
+    unixSeconds: number;
+    rawBody: Buffer | string;
+}): string;
+/** Shape of a parsed `X-Internal-Signature` header. */
+interface ParsedSignature {
+    /** Identifier of the signing key (e.g. `'mcp-v2'`). */
+    keyId: string;
+    /** Unix epoch seconds at signing time. */
+    unixSeconds: number;
+    /** Base64-encoded HMAC-SHA256 digest. */
+    signature: string;
+}
+/**
+ * Parse a `X-Internal-Signature` header value. Returns `null` for
+ * any malformed shape rather than throwing — the api guard converts
+ * `null` to a `401 Unauthorized` so a malformed header never
+ * triggers a `500`.
+ *
+ * Accepted: `v1=<keyId>:<digits>:<base64>`
+ *
+ * Defensive checks:
+ *   - Must start with `v1=` (Q1: explicit version prefix)
+ *   - keyId / signature must be non-empty after split
+ *   - timestamp must parse to a finite, non-negative integer
+ *   - keyId must be ASCII identifier-safe ([A-Za-z0-9_-]+) so a
+ *     malicious header cannot smuggle control chars or whitespace
+ *     into log lines / metric labels
+ *   - signature must be valid base64 (only base64 alphabet chars)
+ */
+declare function parseSignatureHeader(headerValue: string | undefined): ParsedSignature | null;
+/**
+ * Format a ParsedSignature back into a header string. Round-trips
+ * with `parseSignatureHeader` for any validly-shaped input.
+ *
+ * Used by the signing side (HTTP client). Keeping it next to the
+ * parser pins the format in one place.
+ */
+declare function formatSignatureHeader(parsed: ParsedSignature): string;
+
+/**
+ * P1-A14a-2d — pure HMAC signer for outbound /api/internal/**
+ * requests. Lives in SDK so remote-mcp and slack-bot (both of which
+ * already depend on `@vess-id/ai-identity`) can attach
+ * `X-Internal-Signature` to every request without dragging the
+ * api package into their dependency graph.
+ *
+ * Pure (no I/O, no Nest). Mirrors the `utils/crypto.ts` profile:
+ * the only Node-builtin used is `crypto.createHmac`.
+ *
+ * Pairing with the verifier
+ * -------------------------
+ * The verifier (api side, `HmacKeyset.verify` →
+ * `buildCanonicalString` → constant-time compare) reads the same
+ * `buildCanonicalString` from this module by construction. As long
+ * as both sides pass the same `(method, path, unixSeconds, rawBody)`
+ * the HMACs match by definition.
+ *
+ * Body bytes
+ * ----------
+ * The caller MUST pass the exact bytes that go on the wire as
+ * `rawBody`. Re-running `JSON.stringify(...)` on each side would
+ * risk a byte mismatch (object key order is implementation-defined
+ * in spec, even though V8 preserves insertion order in practice).
+ * The api-client `makeRequest` helper computes `JSON.stringify`
+ * once, hands the same string to both `signRequest` and `fetch`.
+ */
+/**
+ * Minimum signer key length in raw bytes. 32 bytes = 256 bits
+ * matches HMAC-SHA256's natural block size and the verifier's
+ * `MIN_KEY_BYTES`. A truncated env var (accidental newline,
+ * copy-paste error) is the realistic failure mode this guards
+ * against.
+ */
+declare const MIN_SIGNER_KEY_BYTES = 32;
+interface InternalHmacSignerKey {
+    /** Stable identifier for the key, e.g. `'mcp-v1'`. Embedded in
+     *  the X-Internal-Signature header so the verifier can pick the
+     *  right key. Must match `/^[A-Za-z0-9_-]+$/`. */
+    keyId: string;
+    /** Raw HMAC secret. >= MIN_SIGNER_KEY_BYTES bytes. */
+    secret: Buffer;
+}
+interface SignRequestArgs {
+    /** HTTP method. Will be upper-cased by `buildCanonicalString`,
+     *  but callers should pass the uppercase form they use on the
+     *  wire so signer and `fetch()` stay in lockstep. */
+    method: string;
+    /** URL path with query string already stripped (verifier does
+     *  `request.originalUrl?.split('?')[0]`; signer must mirror).
+     *  Path encoding (e.g. `%2F` vs `/`) is caller's responsibility
+     *  — the canonical string treats them as different bytes. */
+    path: string;
+    /** Wire bytes. The same string/buffer passed to `fetch({body})`
+     *  must be passed here — `JSON.stringify` runs ONCE per request
+     *  in the caller. */
+    rawBody: Buffer | string;
+    /** Optional fixed timestamp for testing. Defaults to
+     *  `Math.floor(Date.now() / 1000)`. */
+    unixSeconds?: number;
+}
+/**
+ * Sign an outbound request and return a fully-formatted
+ * `X-Internal-Signature` header value. The caller sets the header
+ * on the outbound request directly:
+ *
+ * ```ts
+ * headers[SIGNATURE_HEADER] = signRequest(key, { method, path, rawBody })
+ * ```
+ *
+ * Throws if key material is invalid (bad keyId or short secret) —
+ * surfacing misconfiguration loudly at request time rather than
+ * silently producing a header the verifier will reject.
+ */
+declare function signRequest(key: InternalHmacSignerKey, args: SignRequestArgs): string;
+
 declare const version = "0.0.1";
 
-export { type ABACPolicyEngine, ACTION_PARAMS_MAX_SIZE, ACTION_PREFIXES, ACTION_REGISTRY, AIdentityClient, type AIdentityConfig, AIdentityError, type APIAgent, type APICredential, APIVCManager, type AbacDecision, type AbacInput, type AcceptInvitationRequest, type AckEventResponse, type ActionInputSchema, type ActionMapping, type ActionMeta, type ActionParamDisplay, type ActionRegistry, type ActionRiskLevel, type Agent, type AgentCreateOptions, type AgentDIDConfig, AgentDIDManager, AgentManager, AgentStatus, AgentType, type AgentWithId, AllowAllAbac, type AnyProvider, type ApiKeyValidationResult, type AuditEvent, type AuditQuery, AuthProvider, type AuthState, AuthenticationError, type AutoApproveConfig, type BindingSource, CANONICAL_PROVIDERS, type CanonicalProvider, type CapabilityMeta, type CheckGrantPermissionRequest, type CheckGrantPermissionResult, type CheckPermissionInput, type CheckPermissionResult, type CollectContextRequest, type ConfirmGrantSuggestionRequest, type ConnectorAction, type ConnectorConfig, type ConnectorExecutionContext, type ConnectorResponse, type ConnectorResponseMetadata, type ConnectorTokenConfig, type ConstraintEvaluationResult, ConstraintEvaluator, type ConstraintEvaluatorOptions, type ConstraintViolation, type ConstraintWarning, type ContextBindingSource, type ContextProvider, type CreateGrantRequest, type CreateInvitationRequest, type CreateReceiptRequest, type CredentialRef, CredentialStatus, type CredentialStore, CredentialType, DEFAULT_CONSTRAINTS_BY_RISK, type DIDDocument, type DataAccessVC, type DecisionTrace, type DelegationVC, DeviceEnrollManager, type DeviceEnrollPollResult, type DeviceEnrollServerSideParams, type DeviceEnrollStartParams, type DeviceEnrollStartResult, type DisclosureFields, DummyCreds, DummyVpVerifier, type EmployeeVPRequest, type EvaluationContext, type ExternalActionRequest, FilesystemKeyStorage, GatewayClient, GatewayError, type GatewayEvent, type GetEventsOptions, type GetEventsResponse, type GitHubConfig, type GoogleConfig, type Grant, type GrantConstraints, type GrantResource, GrantResourceType, GrantScope, GrantStatus, type GrantUsage, type IConnectorService, type IStateStore, type Intent, type IntentEvaluationResult, type IntentObligation, type IntentResource, InvalidVPError, type Invitation, type InvitationRole, InvitationStatus, type IssueSDJWTVCRequest, type IssueSDJWTVCResult, type JiraBoard, type JiraConfig, type JiraIssue, type JiraIssueType, type JiraProject, type JiraSprint, type JiraStatus, type JiraUser, type JiraWorklog, type JsonSchema, JsonStateStore, KeyManager, type KeyPairGenerationResult, type KeyStorageConfig, type KeyStorageProvider, LEGACY_RESOURCE_TYPE_MAP, type MemoryDocument, MemoryKeyStorage, MemoryManager, type MemoryQuery, type MemoryQueryResult, NetworkError, type NormalizeIntentRequest, type NormalizedIntent, type OAuthAuthorizeRequest, type OAuthCallbackParams, type OAuthConnection, OAuthProvider, type OAuthToken, type OrganizationConfig, type OrganizationPermission, type OrganizationPolicy, type OrganizationVC, PROVIDER_ALIASES, type ParamBindingSource, type ParsedResourceType, type PermissionConstraints, type PermissionMode, type PermissionResource, type PermissionRule, type PermissionTimeConstraint, type PermissionVcClaims, type PlanDelegationInput, type PlanDelegationResult, type PolicyCondition, type PolicyEvaluationResult, type PolicyInput, type PolicyRule, type PolicyTarget, type Provider, RESOURCE_TYPES, type ReBACChecker, type Receipt, type ReceiptListResult, type ReceiptOutcome, type ReceiptSearchQuery, ReceiptStatus, type Relation, type ResolvedTargets, type ResourceIdBinding, type ResourceRef, type ResourceScope, type ResourceType, type RiskAssessmentResult, type RiskFactor, type RiskLevel, SDJwtClient, ScopeUnmatchedError, type SecondaryBinding, SimpleRebac, type SlackConfig, StandardActionCategory, type SuggestGrantRequest, type SuggestedAction, type SuggestedConstraints, type SuggestedGrant, type SuggestedResource, type SuggestionRiskLevel, TIER_LIMITS, type TargetBindings, type TargetConstraint, TargetResolver, type TierLimits, type TimeWindowCheckResult, type TimeWindowConstraint, type ToolDefinition, type ToolInvocation, ToolManager, type ToolPermissionRequest, type ToolPermissionVC, type UnifiedResourceType, type UpdateGrantRequest, type UserIdentity, type UserIdentityConfig, type UserIdentityCreateOptions, UserIdentityManager, UserKeyPairManager, type UserTier, VALID_MCP_ACTIONS, VALID_MCP_TOOLS, VCExpiredError, VCManager, VCRevokedError, VCStatus, type VCTemplate, VCType, VPManager, type VPRequest, type VerifiablePresentation, type VerificationMethod, type VerifiedVcClaims, type VerifyInvitationResponse, type VerifyReceiptRequest, type VerifyReceiptResult, type VerifySDJWTVCResult, type VpVerifier, WRITE_ACTION_NAMES, type WeeklyReportData, type WeeklyReportSummary, buildGrantIdFields, canonicalizeAction, checkPermissionWithVP, configure, createAjv, createDidJwk, credentialStatusToVCStatus, defaultConstraintEvaluator, evaluateConstraints, extractProjectKey, extractPublicKey, extractPublicKeyFromDid, generateActionParamsDisplay, generateActionSummary, generateKeyPair, generateNonce, getActionAliases, getAllActionForms, getAllValidMcpActionNames, getClient, getDefaultDisclosureFields, getKeyIdFromDid, getRequiredRelations, getRequiredScopes, getTierLimits, getValidMcpActionNames, grantConstraintsToPermissionConstraints, grantToPermissionRules, indexActions, indexCapabilities, isActionEquivalent, isCanonicalProvider, isUnlimited, isValidDidJwk, isValidProvider, isWriteAction, loadActionRegistryFromFile, loadActionRegistryFromObject, normalizeMcpActionName, parseGrantAction, parseGrantResourceType, planDelegationForVC, publicKeysMatch, resolveActionsFromSelection, resolveProvider, resolveResourceType, resolveUserTier, signJWT, validateRegistryObject, vcStatusToCredentialStatus, verifyJWT, version };
+export { type ABACPolicyEngine, ACTION_PARAMS_MAX_SIZE, ACTION_PREFIXES, ACTION_REGISTRY, AIdentityClient, type AIdentityConfig, AIdentityError, type APIAgent, type APICredential, APIVCManager, type AbacDecision, type AbacInput, type AcceptInvitationRequest, type AckEventResponse, type ActionInputSchema, type ActionMapping, type ActionMeta, type ActionParamDisplay, type ActionRegistry, type ActionRiskLevel, type Agent, type AgentCreateOptions, type AgentDIDConfig, AgentDIDManager, AgentManager, AgentStatus, AgentType, type AgentWithId, AllowAllAbac, type AnyProvider, type ApiKeyValidationResult, type AuditEvent, type AuditQuery, AuthProvider, type AuthState, AuthenticationError, type AutoApproveConfig, type BindingSource, type BuildKbJwtPayloadArgs, type BuildKbJwtPayloadDeps, CANONICAL_PROVIDERS, type CanonicalProvider, type CapabilityMeta, type CheckGrantPermissionRequest, type CheckGrantPermissionResult, type CheckPermissionInput, type CheckPermissionResult, type CollectContextRequest, type ConfirmGrantSuggestionRequest, type ConnectorAction, type ConnectorConfig, type ConnectorExecutionContext, type ConnectorResponse, type ConnectorResponseMetadata, type ConnectorTokenConfig, type ConstraintEvaluationResult, ConstraintEvaluator, type ConstraintEvaluatorOptions, type ConstraintViolation, type ConstraintWarning, type ContextBindingSource, type ContextProvider, type CreateGrantRequest, type CreateInvitationRequest, type CreateReceiptRequest, type CredentialRef, CredentialStatus, type CredentialStore, CredentialType, DEFAULT_CONSTRAINTS_BY_RISK, type DIDDocument, type DataAccessVC, type DecisionTrace, type DelegationVC, DeviceEnrollManager, type DeviceEnrollPollResult, type DeviceEnrollServerSideParams, type DeviceEnrollStartParams, type DeviceEnrollStartResult, type DisclosureFields, DummyCreds, DummyVpVerifier, type EmployeeVPRequest, type EvaluationContext, type ExternalActionRequest, FilesystemKeyStorage, GATEWAY_ERROR_CODE, GatewayClient, GatewayError, type GatewayErrorCode, type GatewayEvent, type GetEventsOptions, type GetEventsResponse, type GitHubConfig, type GoogleConfig, type Grant, type GrantConstraints, type GrantResource, GrantResourceType, GrantScope, GrantStatus, type GrantUsage, type IConnectorService, type IStateStore, type Intent, type IntentEvaluationResult, type IntentObligation, type IntentResource, type InternalHmacSignerKey, InvalidVPError, type Invitation, type InvitationRole, InvitationStatus, type IssueSDJWTVCRequest, type IssueSDJWTVCResult, type JiraBoard, type JiraConfig, type JiraIssue, type JiraIssueType, type JiraProject, type JiraSprint, type JiraStatus, type JiraUser, type JiraWorklog, type JsonSchema, JsonStateStore, KB_JWT_DEFAULT_LIFETIME_SECONDS, type KbJwtPayload, KeyManager, type KeyPairGenerationResult, type KeyStorageConfig, type KeyStorageProvider, LEGACY_RESOURCE_TYPE_MAP, MIN_SIGNER_KEY_BYTES, MemoryKeyStorage, NetworkError, type NormalizeIntentRequest, type NormalizedIntent, type OAuthAuthorizeRequest, type OAuthCallbackParams, type OAuthConnection, OAuthProvider, type OAuthToken, type OrganizationConfig, type OrganizationPermission, type OrganizationPolicy, type OrganizationVC, PROVIDER_ALIASES, type ParamBindingSource, type ParsedResourceType, type ParsedSignature, type PermissionConstraints, type PermissionMode, type PermissionResource, type PermissionRule, type PermissionTimeConstraint, type PermissionVcClaims, type PlanDelegationInput, type PlanDelegationResult, type PolicyCondition, type PolicyEvaluationResult, type PolicyInput, type PolicyRule, type PolicyTarget, type Provider, REAUTH_REQUIRED_ACTION, RESOURCE_TYPES, type ReBACChecker, type Receipt, type ReceiptListResult, type ReceiptOutcome, type ReceiptSearchQuery, ReceiptStatus, type Relation, type ResolvedTargets, type ResourceIdBinding, type ResourceRef, type ResourceScope, type ResourceType, type RiskAssessmentResult, type RiskFactor, type RiskLevel, SDJwtClient, SIGNATURE_HEADER, SIGNATURE_VERSION_PREFIX, ScopeUnmatchedError, type SecondaryBinding, type SignRequestArgs, SimpleRebac, type SlackConfig, StandardActionCategory, type SuggestGrantRequest, type SuggestedAction, type SuggestedConstraints, type SuggestedGrant, type SuggestedResource, type SuggestionRiskLevel, TIER_LIMITS, type TargetBindings, type TargetConstraint, TargetResolver, type TierLimits, type TimeWindowCheckResult, type TimeWindowConstraint, type ToolDefinition, type ToolInvocation, ToolManager, type ToolPermissionRequest, type ToolPermissionVC, type UnifiedResourceType, type UpdateGrantRequest, type UserIdentity, type UserIdentityConfig, type UserIdentityCreateOptions, UserIdentityManager, UserKeyPairManager, type UserTier, VALID_MCP_ACTIONS, VALID_MCP_TOOLS, VCExpiredError, VCManager, VCRevokedError, VCStatus, type VCTemplate, VCType, VPManager, type VPRequest, type VerifiablePresentation, type VerificationMethod, type VerifiedVcClaims, type VerifyInvitationResponse, type VerifyReceiptRequest, type VerifyReceiptResult, type VerifySDJWTVCResult, type VpVerifier, WRITE_ACTION_NAMES, type WeeklyReportData, type WeeklyReportSummary, buildCanonicalString, buildGrantIdFields, buildKbJwtPayload, canonicalizeAction, checkPermissionWithVP, configure, createAjv, createDidJwk, credentialStatusToVCStatus, defaultConstraintEvaluator, evaluateConstraints, extractProjectKey, extractPublicKey, extractPublicKeyFromDid, formatSignatureHeader, generateActionParamsDisplay, generateActionSummary, generateKeyPair, generateNonce, getActionAliases, getAllActionForms, getAllValidMcpActionNames, getClient, getDefaultDisclosureFields, getKeyIdFromDid, getRequiredRelations, getRequiredScopes, getTierLimits, getValidMcpActionNames, grantConstraintsToPermissionConstraints, grantToPermissionRules, indexActions, indexCapabilities, isActionEquivalent, isCanonicalProvider, isUnlimited, isValidDidJwk, isValidProvider, isWriteAction, loadActionRegistryFromFile, loadActionRegistryFromObject, normalizeDomain, normalizeMcpActionName, parseGrantAction, parseGrantResourceType, parseSignatureHeader, planDelegationForVC, publicKeysMatch, readVcExpSeconds, resolveActionsFromSelection, resolveProvider, resolveResourceType, resolveUserTier, sha256Hex, signJWT, signRequest, validateRegistryObject, vcStatusToCredentialStatus, verifyJWT, version };