@adastracomputing/ink 0.1.0-alpha.3 → 0.1.0-alpha.5

package/dist/crypto/ink.d.ts

@@ -0,0 +1,178 @@
+declare function base64urlEncode(bytes: Uint8Array): string;
+declare function base64urlDecode(str: string): Uint8Array;
+declare function hexToBytes(hex: string): Uint8Array;
+declare function bytesToHex(bytes: Uint8Array): string;
+declare function jcsCanonicalize(obj: unknown): string;
+export interface InkSignInput {
+    method: string;
+    path: string;
+    recipientDid: string;
+    body: Record<string, unknown>;
+    timestamp: string;
+}
+export declare function buildSignatureBase(input: InkSignInput): string;
+/**
+ * Sign an INK message. Returns the base64url-encoded Ed25519 signature.
+ */
+export declare function signInkMessage(input: InkSignInput, privateKey: Uint8Array): Promise<string>;
+/**
+ * Verify an INK message signature.
+ * Returns false (never throws) for malformed or wrong-length signatures.
+ */
+export declare function verifyInkSignature(input: InkSignInput, signatureBase64url: string, publicKey: Uint8Array): Promise<boolean>;
+/**
+ * Build the Authorization header value for an INK request.
+ * Optionally includes keyId for key-rotation-aware verification.
+ *
+ * Both values are validated against the same grammar the receiver uses so that
+ * invalid characters (including CR/LF that could cause header injection) are
+ * rejected before they reach the HTTP layer.
+ */
+export declare function buildAuthHeader(signatureBase64url: string, keyId?: string): string;
+export interface InkEncryptedEnvelope {
+    protocol: "ink/0.1";
+    type: "network.tulpa.encrypted";
+    from: string;
+    ephemeralKey: string;
+    nonce: string;
+    ciphertext: string;
+    timestamp: string;
+    messageNonce: string;
+}
+export interface InkEncryptResult {
+    envelope: InkEncryptedEnvelope;
+    ephemeralPublicKey: Uint8Array;
+}
+/**
+ * Encrypt an INK message payload using ECIES:
+ *   1. Generate ephemeral X25519 keypair (or accept one for deterministic tests)
+ *   2. ECDH with recipient's X25519 public key
+ *   3. HKDF-SHA256(sharedSecret, salt="ink/0.1", info="ink/0.1/encrypt") → 32-byte AES key
+ *   4. AES-256-GCM encrypt the JSON-serialized plaintext
+ *   5. Pack into outer envelope
+ */
+export declare function encryptInkPayload(plaintext: Record<string, unknown>, senderDid: string, recipientEncryptionKeyHex: string, timestamp: string, messageNonce: string, options?: {
+    ephemeralPrivateKey?: Uint8Array;
+    aesNonce?: Uint8Array;
+}): Promise<InkEncryptResult>;
+/**
+ * Decrypt an INK encrypted envelope using the recipient's X25519 private key.
+ * Returns the decrypted inner envelope and verifies inner/outer consistency.
+ */
+export declare function decryptInkPayload(envelope: InkEncryptedEnvelope, recipientEncryptionPrivateKeyHex: string, recipientDid?: string): Promise<Record<string, unknown>>;
+export interface ReplayCheckInput {
+    messageTimestamp: string;
+    receiverClock: string;
+    nonce: string;
+    previouslySeenNonces: string[];
+}
+export interface ReplayCheckResult {
+    accepted: boolean;
+    errorCode?: "expired_message" | "duplicate_nonce";
+}
+export declare const MAX_TIMESTAMP_AGE_MS: number;
+export declare const MAX_FUTURE_TIMESTAMP_MS: number;
+/**
+ * Check whether an INK message should be accepted or rejected
+ * based on timestamp freshness and nonce deduplication (§3.5).
+ */
+export declare function checkReplay(input: ReplayCheckInput): ReplayCheckResult;
+/**
+ * Compute SHA-256 hash of JCS-canonicalized body. Returns hex string.
+ * Used for messageHash in receipts and previousEventHash in audit chains.
+ */
+export declare function computeMessageHash(body: Record<string, unknown>): Promise<string>;
+/**
+ * Sign an INK audit event. Returns base64url-encoded Ed25519 signature.
+ * Signs the JCS-canonicalized event with the agentSignature field excluded.
+ */
+export declare function signAuditEvent(event: Record<string, unknown>, privateKey: Uint8Array): Promise<string>;
+/**
+ * Verify an INK audit event signature.
+ * Returns false (never throws) for malformed or wrong-length signatures.
+ */
+export declare function verifyAuditEventSignature(event: Record<string, unknown>, publicKey: Uint8Array): Promise<boolean>;
+/**
+ * Compute the RFC 6962 Merkle leaf hash for an INK audit event:
+ *
+ *   SHA-256(0x00 || JCS(event-without-agentSignature))
+ *
+ * This is the leaf-hashing rule a witness MUST use when building its
+ * transparency log (Auditability §7.3). It is distinct from
+ * `computeEventHash`, which omits the 0x00 prefix and is used only for
+ * `previousEventHash` chain linkage inside the agent's local audit log.
+ *
+ * Returns the lowercase-hex digest.
+ */
+export declare function computeAuditMerkleLeafHash(event: Record<string, unknown>): Promise<string>;
+/**
+ * Compute SHA-256 hash of JCS-canonicalized audit event (excluding agentSignature).
+ * Used for previousEventHash chain linkage. NOT the Merkle leaf hash:
+ * see `computeAuditMerkleLeafHash` for the RFC 6962 leaf-hash rule used
+ * by witness transparency logs.
+ */
+export declare function computeEventHash(event: Record<string, unknown>): Promise<string>;
+/**
+ * Sign an INK audit response. Returns base64url-encoded Ed25519 signature.
+ * Domain-separated: signs "ink/audit-response\n" + JCS(events) to prevent
+ * cross-protocol signature replay.
+ */
+export declare function signAuditResponse(events: unknown[], privateKey: Uint8Array): Promise<string>;
+/**
+ * Verify an INK audit response signature.
+ * Expects the domain-separated format: "ink/audit-response\n" + JCS(events).
+ * Returns false (never throws) for malformed or wrong-length signatures.
+ */
+export declare function verifyAuditResponseSignature(events: unknown[], signature: string, publicKey: Uint8Array): Promise<boolean>;
+/**
+ * Validate the internal continuity of an audit event chain. Distinct
+ * from verifyAuditResponseSignature, which only verifies the response
+ * wrapper signature. Callers fetching audit responses MUST call both:
+ * the signature gate proves the witness/agent attested to this slice,
+ * this gate proves the slice itself is contiguous and fork-free.
+ *
+ * Rules enforced:
+ * - input must be an array of non-null plain objects
+ * - each event must have integer sequence and string-or-null previousEventHash
+ * - sequences within the response must be strictly increasing by 1
+ *   (a partial-window response anchored elsewhere is fine, but no internal gaps)
+ * - duplicate sequence numbers within the response are a fork
+ * - events[i].previousEventHash MUST equal computeEventHash(events[i-1]) for i >= 1
+ * - events[0].previousEventHash is NOT verified against any external
+ *   anchor; callers that have one (a prior pinned event hash) must
+ *   verify the boundary themselves
+ */
+export declare function verifyAuditEventChain(events: unknown): Promise<{
+    valid: true;
+} | {
+    valid: false;
+    error: "invalid_input" | "invalid_event" | "sequence_gap" | "sequence_fork" | "previous_hash_mismatch";
+}>;
+/**
+ * Sign an INK audit-query response from a witness. The signed bytes are:
+ *
+ *   "ink/audit-query-response/v1\n" + JCS(response object minus serviceSignature)
+ *
+ * Callers pass the response object EXCLUDING `serviceSignature`. The
+ * canonical bytes bind every other field, including `protocol`, `type`,
+ * `messageId`, `events`, `proofs`, `treeSize`, `rootHash`, `serviceDid`,
+ * and `timestamp`, so verifiers cannot rebind a valid signature to a
+ * different witness/message/root.
+ */
+export declare function signAuditQueryResponse(responseWithoutSignature: Record<string, unknown>, privateKey: Uint8Array): Promise<string>;
+/**
+ * Verify the Ed25519 signature on an audit-query response. This is the
+ * LOW-LEVEL primitive. Most consumers should call
+ * `verifyAuditQueryResponse` (from `src/audit/inclusion-receipt.ts`)
+ * instead: it enforces envelope shape, requester binding, the
+ * events-to-proofs one-to-one mapping, and walks every Merkle proof.
+ *
+ * Calling this function alone does NOT prove the response is acceptable.
+ * A signed but malformed envelope (wrong type, wrong protocol, no
+ * proofs, wrong requester) can still pass here. Caller is responsible
+ * for pinning / resolving the witness public key out of band (e.g.
+ * via /.well-known/did.json). Returns false (never throws) for any
+ * malformed input.
+ */
+export declare function verifyAuditQueryResponseSignature(responseWithoutSignature: Record<string, unknown>, signature: string, publicKey: Uint8Array): Promise<boolean>;
+export { base64urlEncode, base64urlDecode, hexToBytes, bytesToHex, jcsCanonicalize };