@tinycloud/sdk-services 2.2.0-beta.7 → 2.2.1-beta.0

package/dist/encryption/index.d.ts

@@ -0,0 +1,802 @@
+import { c as IService, e as Result, B as BaseService } from '../BaseService-C_iXlTeN.js';
+
+/**
+ * Canonical JSON serialization and content hashing for TinyCloud
+ * encryption requests/responses.
+ *
+ * The node and SDK must agree byte-for-byte on the canonical form so
+ * that body-hash bindings (`bodyHash`, `encryptedSymmetricKeyHash`,
+ * `receiverPublicKeyHash`) verify on both sides.
+ *
+ * Canonical rules:
+ * - Object keys are sorted lexicographically by code point.
+ * - Strings are encoded with the JSON.stringify default (RFC 8259).
+ * - Numbers are emitted via JSON.stringify; callers should restrict to
+ *   integers or use string fields for high-precision values.
+ * - `undefined` properties are dropped. `null` is preserved.
+ * - Arrays preserve element order.
+ *
+ * Hashing uses SHA-256 supplied by the caller (via an `EncryptionCrypto`
+ * binding) so this module stays platform-agnostic.
+ */
+type Json = null | boolean | number | string | Json[] | {
+    [key: string]: Json | undefined;
+};
+/**
+ * Produce the canonical JSON string for {@link value}. Object keys are
+ * sorted, `undefined` properties are dropped, and primitive types are
+ * encoded by `JSON.stringify`.
+ */
+declare function canonicalize(value: Json | undefined): string;
+declare function hexEncode(bytes: Uint8Array): string;
+declare function hexDecode(hex: string): Uint8Array;
+declare function base64Encode(bytes: Uint8Array): string;
+declare function base64Decode(s: string): Uint8Array;
+declare function utf8Encode(s: string): Uint8Array;
+declare function utf8Decode(b: Uint8Array): string;
+/**
+ * Compute `hexEncode(sha256(canonicalize(value)))`. The SHA-256 binding
+ * is injected so the module remains usable in both the WASM and pure-JS
+ * paths.
+ */
+declare function canonicalHashHex(sha256: (bytes: Uint8Array) => Uint8Array, value: Json): string;
+
+/**
+ * Type definitions for TinyCloud one-of-one encryption.
+ *
+ * Wire shapes mirror the protocol described in the encryption
+ * architecture: inline envelopes carry the encrypted symmetric key
+ * alongside the ciphertext; decrypt requests are short-lived UCAN
+ * invocations against a target node plus networkId.
+ */
+
+/** Default ciphersuite identifier for v1 envelopes. */
+declare const DEFAULT_ENCRYPTION_ALG: "x25519-aes256gcm/v1";
+/** Inline-envelope schema version. */
+declare const ENVELOPE_VERSION: 1;
+/** Default key version on freshly-created networks. */
+declare const DEFAULT_KEY_VERSION: 1;
+/** Decrypt-invocation fact type. */
+declare const DECRYPT_FACT_TYPE: "tinycloud.encryption.decrypt/v1";
+/** Decrypt response type. */
+declare const DECRYPT_RESULT_TYPE: "tinycloud.encryption.decrypt-result/v1";
+/** Encryption service identifier (manifest long form). */
+declare const ENCRYPTION_SERVICE: "tinycloud.encryption";
+/** Short form used in recap/abilities maps. */
+declare const ENCRYPTION_SERVICE_SHORT: "encryption";
+/** Decrypt ability URN. */
+declare const DECRYPT_ACTION: "tinycloud.encryption/decrypt";
+/**
+ * Inline encrypted envelope persisted in KV/SQL records.
+ *
+ * - `encryptedSymmetricKey` is opaque to the SDK; only the network can
+ *   unwrap it.
+ * - `encryptedSymmetricKeyHash` is the canonical hash of the wrapped key
+   *   bytes (hex-encoded sha-256 of the base64 string's canonical JSON
+   *   form). The node recomputes this on every decrypt request.
+ * - `ciphertext` and `aad` are payload bytes only; the node never sees
+ *   them.
+ */
+interface InlineEncryptedEnvelope {
+    /** Schema version. */
+    v: typeof ENVELOPE_VERSION;
+    /** Network id URN. */
+    networkId: string;
+    /** Ciphersuite identifier. */
+    alg: string;
+    /** Network key version that was used to wrap the symmetric key. */
+    keyVersion: number;
+    /** Base64-encoded wrapped symmetric key / capsule. */
+    encryptedSymmetricKey: string;
+    /** Hex sha-256 of the canonical encryptedSymmetricKey string. */
+    encryptedSymmetricKeyHash: string;
+    /** Base64-encoded payload ciphertext. */
+    ciphertext: string;
+    /** Base64-encoded associated data, if any. */
+    aad?: string;
+    /** Caller-supplied metadata. Not authenticated against the node. */
+    metadata?: Record<string, string>;
+}
+/**
+ * Node-published network descriptor. The node DB is authoritative; a
+ * cached copy may also live under
+ * `.well-known/encryption/network/<name>` in the principal's account
+ * space (a discovery record only).
+ */
+interface NetworkDescriptor {
+    networkId: string;
+    principal: string;
+    name: string;
+    members: ReadonlyArray<{
+        nodeId: string;
+        role: "primary" | "share";
+    }>;
+    threshold: {
+        n: number;
+        t: number;
+    };
+    state: "pending" | "generating" | "active" | "rotating" | "revoked" | "failed";
+    /** Base64-encoded network public key. */
+    publicEncryptionKey: string;
+    alg: string;
+    keyVersion: number;
+    keyBackend: "local-one-of-one" | "dstack" | "threshold";
+    createdAt: string;
+    updatedAt: string;
+}
+/**
+ * Decrypt-request body sent over the wire. Hashed (canonically) and
+ * bound to the UCAN invocation via `facts.bodyHash`.
+ */
+interface DecryptRequestBody {
+    type: typeof DECRYPT_FACT_TYPE;
+    targetNode: string;
+    networkId: string;
+    alg: string;
+    keyVersion: number;
+    /** Base64-encoded wrapped symmetric key from the envelope. */
+    encryptedSymmetricKey: string;
+    /** Recomputed hash of the wrapped key. */
+    encryptedSymmetricKeyHash: string;
+    /** Base64-encoded per-request receiver public key. */
+    receiverPublicKey: string;
+    /** Hash of the receiver public key. */
+    receiverPublicKeyHash: string;
+}
+/**
+ * Decrypt-response body returned by the node. The SDK verifies the
+ * signature, recomputes hashes, then unwraps `wrappedKey` with the
+ * per-request receiver private key before decrypting the payload.
+ */
+interface DecryptResponseBody {
+    type: typeof DECRYPT_RESULT_TYPE;
+    targetNode: string;
+    networkId: string;
+    invocationCid: string;
+    encryptedSymmetricKeyHash: string;
+    receiverPublicKeyHash: string;
+    /** Base64-encoded symmetric key re-encrypted to receiverPublicKey. */
+    wrappedKey: string;
+    alg: string;
+    keyVersion: number;
+    requestHash: string;
+    nodeId: string;
+    /** Base64-encoded ed25519 signature over canonical(response - signature field). */
+    nodeSignature: string;
+}
+/**
+ * Decrypt-invocation facts attached to the UCAN. Verifiers recompute
+ * `bodyHash`, `encryptedSymmetricKeyHash`, and `receiverPublicKeyHash`
+ * from the request body and reject any mismatch.
+ */
+interface DecryptInvocationFact {
+    type: typeof DECRYPT_FACT_TYPE;
+    targetNode: string;
+    networkId: string;
+    bodyHash: string;
+    encryptedSymmetricKeyHash: string;
+    receiverPublicKeyHash: string;
+    alg: string;
+    keyVersion: number;
+}
+/**
+ * Per-request receiver key pair (x25519). The private key never
+ * leaves the SDK; the public key is sent to the node so the node can
+ * rewrap the symmetric key.
+ */
+interface ReceiverKeyPair {
+    publicKey: Uint8Array;
+    privateKey: Uint8Array;
+}
+/**
+ * Crypto primitives injected into the encryption module. The SDK
+ * provides these via WASM bindings; tests provide simple in-memory
+ * implementations.
+ */
+interface EncryptionCrypto {
+    /** SHA-256 → 32-byte digest. */
+    sha256(data: Uint8Array): Uint8Array;
+    /** Cryptographically secure random bytes. */
+    randomBytes(length: number): Uint8Array;
+    /** Derive an x25519 key pair from a 32-byte seed. */
+    x25519FromSeed(seed: Uint8Array): ReceiverKeyPair;
+    /** Compute the x25519 ECDH shared secret. */
+    x25519Dh(privateKey: Uint8Array, publicKey: Uint8Array): Uint8Array;
+    /** Authenticated symmetric encryption (the node's symmetric scheme). */
+    authEncrypt(key: Uint8Array, plaintext: Uint8Array, aad?: Uint8Array): Uint8Array;
+    /** Authenticated symmetric decryption (matched to authEncrypt). */
+    authDecrypt(key: Uint8Array, ciphertext: Uint8Array, aad?: Uint8Array): Uint8Array;
+    /**
+     * Wrap a symmetric key for the network's public encryption key using
+     * a sealed-box / hpke / x25519+symmetric construction. Implementation
+     * is opaque; only the node can unwrap.
+     */
+    sealToNetworkKey(networkPublicKey: Uint8Array, symmetricKey: Uint8Array): Uint8Array;
+    /**
+     * Open a wrapped symmetric key that was re-encrypted to the
+     * per-request receiver public key. The matching private key must be
+     * supplied here; the SDK never sends it to the node.
+     */
+    openWithReceiverKey(receiverPrivateKey: Uint8Array, wrappedKey: Uint8Array): Uint8Array;
+    /**
+     * Verify an ed25519 signature over `message` produced by the node
+     * identified by `nodeId` (the public-key DID).
+     */
+    verifyNodeSignature(nodeId: string, message: Uint8Array, signature: Uint8Array): boolean;
+}
+/**
+ * Signer interface used to derive a receiver key pair from a wallet or
+ * session signer. The signature is HKDF-extracted into the receiver
+ * seed so the public key is reproducible given the same context.
+ */
+interface ReceiverKeySigner {
+    signMessage(message: string): Promise<string>;
+}
+/** Capability proof material accompanying a decrypt invocation. */
+interface DecryptCapabilityProof {
+    /** Delegation chain CIDs rooted at the network principal. */
+    proofs: ReadonlyArray<string>;
+    /** Optional Authorization header value to use instead of building one. */
+    authorization?: string;
+}
+/**
+ * Inputs to the decrypt invocation builder.
+ */
+interface BuildDecryptInvocationInput {
+    /** Target node DID — also the UCAN audience. */
+    targetNode: string;
+    /** Network id URN — also the recap resource. */
+    networkId: string;
+    /** Canonical body that will be POSTed. */
+    body: DecryptRequestBody;
+    /** Facts include hashes bound to the canonical body. */
+    facts: DecryptInvocationFact;
+    /** Capability proof chain. */
+    proof: DecryptCapabilityProof;
+    /** Optional `nbf` UCAN field as an ISO date string. */
+    notBefore?: string;
+    /** Optional `exp` UCAN field as an ISO date string. */
+    expiration?: string;
+}
+/**
+ * The output of {@link buildDecryptInvocation}.
+ */
+interface BuiltDecryptInvocation {
+    /** HTTP `Authorization` header value. */
+    authorization: string;
+    /** CID of the invocation (used by the node response binding). */
+    invocationCid: string;
+    /** Canonical body string the node will hash. */
+    canonicalBody: string;
+}
+/**
+ * Signer interface for producing the decrypt invocation. WASM bindings
+ * implement this with the same session signer used for KV/SQL
+ * invocations; tests can stub it.
+ */
+interface DecryptInvocationSigner {
+    signDecryptInvocation(input: BuildDecryptInvocationInput): Promise<BuiltDecryptInvocation>;
+}
+/**
+ * Errors thrown / returned from the encryption module.
+ */
+type EncryptionErrorInput = {
+    code: "NETWORK_NOT_FOUND";
+    networkId?: string;
+    name?: string;
+    message?: string;
+} | {
+    code: "NETWORK_NOT_ACTIVE";
+    state: string;
+    message?: string;
+} | {
+    code: "INVALID_NETWORK_ID";
+    message: string;
+} | {
+    code: "INVALID_ENVELOPE";
+    message: string;
+} | {
+    code: "DECRYPT_DENIED";
+    message: string;
+} | {
+    code: "INVALID_RESPONSE";
+    message: string;
+} | {
+    code: "RESPONSE_SIGNATURE_INVALID";
+    message?: string;
+} | {
+    code: "RESPONSE_BINDING_MISMATCH";
+    field: string;
+    message?: string;
+} | {
+    code: "TRANSPORT_ERROR";
+    cause: Error;
+    message?: string;
+} | {
+    code: "INVALID_INPUT";
+    message: string;
+};
+type EncryptionError = EncryptionErrorInput & {
+    service: "encryption";
+    message: string;
+};
+declare function encryptionError(input: EncryptionErrorInput): EncryptionError;
+/** Re-export for ergonomic typing of canonical payloads. */
+type CanonicalJson = Json;
+
+/**
+ * Network-descriptor discovery.
+ *
+ * Resolution order (per architecture):
+ *
+ * 1. The node's authoritative endpoint
+ *    `GET /encryption/networks/<networkId>` returns the current
+ *    descriptor (`state`, `publicEncryptionKey`, `keyVersion`, ...).
+ * 2. If the node is unreachable, fall back to the cached discovery
+ *    record at `.well-known/encryption/network/<name>` inside the
+ *    principal's public space.
+ *
+ * The node DB is authoritative on conflict; cached records are
+ * advisory only.
+ */
+
+type DiscoverySource = "node" | "well-known";
+interface DiscoveredNetwork {
+    descriptor: NetworkDescriptor;
+    source: DiscoverySource;
+}
+interface NodeDescriptorFetcher {
+    /** Fetch the descriptor by full networkId URN. */
+    fetchByNetworkId(networkId: string): Promise<NetworkDescriptor | null>;
+}
+interface WellKnownDescriptorFetcher {
+    /**
+     * Read the cached well-known descriptor by principal + network name.
+     * Returns null if no record exists or the record is unreadable.
+     */
+    fetchWellKnown(principal: string, discoveryKey: string): Promise<NetworkDescriptor | null>;
+}
+interface DiscoverNetworkInput {
+    /** Either a networkId URN or a bare network name (paired with `principal`). */
+    identifier: string;
+    /** Required when identifier is a bare name. */
+    principal?: string;
+    node?: NodeDescriptorFetcher;
+    wellKnown?: WellKnownDescriptorFetcher;
+}
+/**
+ * Resolve a network descriptor. The node fetcher is preferred; the
+ * well-known fallback is used only on transport failure.
+ *
+ * The returned descriptor is sanity-checked: `networkId`, `principal`,
+ * and `name` must agree with the URN, and the public key field must
+ * be non-empty.
+ */
+declare function discoverNetwork(input: DiscoverNetworkInput): Promise<{
+    ok: true;
+    data: DiscoveredNetwork;
+} | {
+    ok: false;
+    error: EncryptionError;
+}>;
+/**
+ * Reject a descriptor that is not in a state that accepts decrypt
+ * requests. Only `active` and `rotating` networks may decrypt; revoked
+ * or pending networks reject.
+ */
+declare function ensureNetworkUsableForDecrypt(descriptor: NetworkDescriptor): {
+    ok: true;
+    data: NetworkDescriptor;
+} | {
+    ok: false;
+    error: EncryptionError;
+};
+
+/**
+ * IEncryptionService - Interface for the TinyCloud encryption service.
+ *
+ * Provides:
+ * - Network discovery
+ * - Local encrypt-to-network (no node round-trip)
+ * - Node-mediated decrypt (one-of-one or threshold; v1 is one-of-one)
+ *
+ * The service does NOT own KV/SQL access. Callers fetch encrypted
+ * envelopes from their data service of choice and pass them in.
+ */
+
+interface EncryptToNetworkOptions {
+    /** Optional associated authenticated data (bytes). */
+    aad?: Uint8Array;
+    /** Ciphersuite override. Defaults to the network's alg. */
+    alg?: string;
+    /** Key version override. Defaults to the network's current key version. */
+    keyVersion?: number;
+    /** Caller-supplied envelope metadata. */
+    metadata?: Record<string, string>;
+}
+interface DecryptEnvelopeOptions {
+    /**
+     * Pre-discovered descriptor for the envelope's network. When omitted
+     * the service performs discovery internally.
+     */
+    descriptor?: NetworkDescriptor;
+    /** Optional associated data; must match what was used at encryption time. */
+    aad?: Uint8Array;
+    /** Override the target node id when the descriptor advertises many. */
+    targetNode?: string;
+}
+interface IEncryptionService extends IService {
+    /**
+     * Look up a network's descriptor.
+     *
+     * `identifier` may be either a full networkId URN
+     * (`urn:tinycloud:encryption:did:key:...:default`) or a bare network
+     * name. The bare name form requires the principal to be supplied via
+     * `principal`.
+     */
+    discoverNetwork(identifier: string, principal?: string): Promise<Result<NetworkDescriptor, EncryptionError>>;
+    /**
+     * Encrypt plaintext to the network's public key locally. The result
+     * is an inline envelope ready to persist (KV/SQL).
+     */
+    encryptToNetwork(networkId: string, plaintext: Uint8Array, options?: EncryptToNetworkOptions): Promise<Result<InlineEncryptedEnvelope, EncryptionError>>;
+    /**
+     * Decrypt an inline envelope via the node.
+     *
+     * Steps: generate per-request receiver key, build & sign the
+     * decrypt invocation, POST it to the node, verify the signed
+     * response, open `wrappedKey`, and decrypt the payload locally.
+     *
+     * The capability proof must root at the network principal embedded
+     * in the envelope's networkId.
+     */
+    decryptEnvelope(envelope: InlineEncryptedEnvelope, capabilityProof: DecryptCapabilityProof, options?: DecryptEnvelopeOptions): Promise<Result<Uint8Array, EncryptionError>>;
+}
+
+/**
+ * EncryptionService — TinyCloud one-of-one encryption service.
+ *
+ * Responsibilities:
+ * - Network discovery (`discoverNetwork`).
+ * - Local envelope encryption (`encryptToNetwork`).
+ * - Node-mediated decrypt with full request/response binding
+ *   verification (`decryptEnvelope`).
+ *
+ * Non-responsibilities:
+ * - KV/SQL access. Callers fetch encrypted envelopes from their data
+ *   service of choice and pass them in.
+ * - Network onboarding/ceremony. Those routes are node-only.
+ */
+
+/**
+ * Transport for posting decrypt requests to a TinyCloud node.
+ *
+ * Implementations supply the `Authorization` header (built by the
+ * decrypt-invocation signer) and POST the canonical body. The
+ * response body is JSON-decoded into a {@link DecryptResponseBody}.
+ */
+interface DecryptTransport {
+    postDecrypt(input: {
+        targetNode: string;
+        networkId: string;
+        authorization: string;
+        canonicalBody: string;
+    }): Promise<DecryptResponseBody>;
+}
+interface EncryptionServiceConfig {
+    crypto: EncryptionCrypto;
+    signer: DecryptInvocationSigner;
+    transport: DecryptTransport;
+    node?: NodeDescriptorFetcher;
+    wellKnown?: WellKnownDescriptorFetcher;
+    [key: string]: unknown;
+}
+declare class EncryptionService extends BaseService implements IEncryptionService {
+    static readonly serviceName = "encryption";
+    protected _config: EncryptionServiceConfig;
+    constructor(config: EncryptionServiceConfig);
+    get config(): EncryptionServiceConfig;
+    private get crypto();
+    discoverNetwork(identifier: string, principal?: string): Promise<Result<NetworkDescriptor, EncryptionError>>;
+    encryptToNetwork(networkId: string, plaintext: Uint8Array, options?: EncryptToNetworkOptions): Promise<Result<InlineEncryptedEnvelope, EncryptionError>>;
+    decryptEnvelope(envelope: InlineEncryptedEnvelope, capabilityProof: DecryptCapabilityProof, options?: DecryptEnvelopeOptions): Promise<Result<Uint8Array, EncryptionError>>;
+}
+
+/**
+ * TinyCloud encryption network identifiers.
+ *
+ * A network id is `urn:tinycloud:encryption:<principal>:<network>` where
+ * `principal` is a DID (typically `did:key:...`) and `network` is a
+ * non-empty label drawn from `[a-z0-9][a-z0-9-]*`.
+ *
+ * The embedded principal is the root authority for the network: any
+ * delegation chain ending in a `tinycloud.encryption/decrypt` grant on
+ * the network must root at this principal.
+ */
+interface ParsedNetworkId {
+    /** The full URN string. */
+    networkId: string;
+    /** Principal DID embedded in the URN (the network's root authority). */
+    principal: string;
+    /** Network label (the suffix after the principal). */
+    name: string;
+}
+declare class NetworkIdError extends Error {
+    constructor(message: string);
+}
+/**
+ * Parse a network id string into its principal and name components.
+ *
+ * Throws {@link NetworkIdError} when the input does not match
+ * `urn:tinycloud:encryption:<did>:<name>`, when the embedded DID is
+ * malformed, or when the network name fails {@link NETWORK_NAME_RE}.
+ */
+declare function parseNetworkId(networkId: string): ParsedNetworkId;
+/**
+ * Construct a network id URN from a principal DID and a network name.
+ * Validates inputs and throws {@link NetworkIdError} on bad shape.
+ */
+declare function buildNetworkId(principal: string, name: string): string;
+/**
+ * Returns true when {@link networkId} is a syntactically valid network URN.
+ */
+declare function isNetworkId(networkId: unknown): networkId is string;
+/**
+ * Resolve the discovery key used to look up a network's descriptor under
+ * a principal's public account-space.
+ *
+ * Format: `.well-known/encryption/network/<name>`.
+ */
+declare function networkDiscoveryKey(name: string): string;
+declare const ENCRYPTION_NETWORK_URN_PREFIX = "urn:tinycloud:encryption:";
+declare const NETWORK_NAME_PATTERN: RegExp;
+
+/**
+ * Inline-envelope encrypt / decrypt helpers.
+ *
+ * Encryption is fully local: the SDK generates a per-record symmetric
+ * key, encrypts the payload, then wraps the symmetric key against the
+ * network's public encryption key. The wrapped key (and key hash)
+ * travels alongside the ciphertext inside an
+ * {@link InlineEncryptedEnvelope}.
+ *
+ * Decryption is split: the node unwraps the symmetric key to the
+ * per-request receiver public key (see {@link buildDecryptInvocation}
+ * and the decrypt route); this module is responsible for the local
+ * payload decryption once the symmetric key is available.
+ */
+
+interface EncryptToNetworkInput {
+    /** Target network id URN. */
+    networkId: string;
+    /** Network public key bytes (already discovered). */
+    networkPublicKey: Uint8Array;
+    /** Payload bytes to encrypt. Callers serialize objects to bytes themselves. */
+    plaintext: Uint8Array;
+    /** Optional associated authenticated data. */
+    aad?: Uint8Array;
+    /** Ciphersuite identifier. Defaults to {@link DEFAULT_ENCRYPTION_ALG}. */
+    alg?: string;
+    /** Key version. Defaults to {@link DEFAULT_KEY_VERSION}. */
+    keyVersion?: number;
+    /** Caller-supplied envelope metadata. */
+    metadata?: Record<string, string>;
+}
+interface EncryptToNetworkResult {
+    envelope: InlineEncryptedEnvelope;
+    /** Symmetric key returned for caller bookkeeping; do NOT persist. */
+    symmetricKey: Uint8Array;
+}
+/**
+ * Local-only encrypt: generates a symmetric key, encrypts the payload,
+ * wraps the key against the network public key, and returns the
+ * inline envelope.
+ */
+declare function encryptToNetwork(crypto: EncryptionCrypto, input: EncryptToNetworkInput): EncryptToNetworkResult;
+/**
+ * Validate an inline envelope shape. Returns an error if the envelope
+ * is missing required fields or fails internal hash recomputation.
+ */
+declare function validateEnvelope(crypto: EncryptionCrypto, envelope: unknown): {
+    ok: true;
+    data: InlineEncryptedEnvelope;
+} | {
+    ok: false;
+    error: EncryptionError;
+};
+/**
+ * Decrypt an inline envelope given the unwrapped symmetric key.
+ *
+ * Callers typically obtain the symmetric key via the node decrypt
+ * endpoint plus the per-request receiver key pair (see
+ * `EncryptionService.decryptEnvelope`).
+ */
+declare function decryptEnvelopeWithKey(crypto: EncryptionCrypto, envelope: InlineEncryptedEnvelope, symmetricKey: Uint8Array): Uint8Array;
+
+/**
+ * Per-request receiver key generation.
+ *
+ * The receiver key pair is generated for a single decrypt request: the
+ * SDK sends `receiverPublicKey` to the node so the node can rewrap the
+ * symmetric key; the matching private key never leaves the SDK.
+ *
+ * Two derivation modes are supported:
+ *
+ * 1. **Random** — `crypto.randomBytes(32)` seeds a fresh x25519 pair.
+ *    This is the default for one-of-one flows.
+ *
+ * 2. **Signed-context** — the caller provides a signer that signs a
+ *    deterministic context message (network id + nonce + invocation
+ *    intent). The signature bytes are SHA-256'd into the seed. This is
+ *    useful when callers want the receiver key to be reproducible by
+ *    the same session signer (e.g. for delegated reads where the
+ *    signer is the only stable secret).
+ */
+
+interface RandomReceiverKeyInput {
+    crypto: EncryptionCrypto;
+}
+declare function generateRandomReceiverKey(input: RandomReceiverKeyInput): ReceiverKeyPair;
+interface SignedReceiverKeyInput {
+    crypto: EncryptionCrypto;
+    signer: ReceiverKeySigner;
+    networkId: string;
+    /** Optional extra context (e.g. invocation nonce) folded into the message. */
+    context?: string;
+}
+/**
+ * Deterministic receiver-key derivation: signs a context string with
+ * the supplied signer, then SHA-256s the signature bytes into the
+ * x25519 seed.
+ *
+ * The context message is:
+ *   `tinycloud.encryption.receiver-key/v1:<networkId>:<context>`
+ *
+ * Callers MUST include unique context (e.g. a fresh nonce) on every
+ * request unless they explicitly want reproducibility.
+ */
+declare function deriveSignedReceiverKey(input: SignedReceiverKeyInput): Promise<ReceiverKeyPair>;
+
+/**
+ * TinyCloud encryption decrypt-invocation builder.
+ *
+ * The decrypt invocation is a UCAN-style TinyCloud invocation against
+ * a node plus a network id. It is structurally distinct from the
+ * existing space-shaped invocations:
+ *
+ * - `aud` (audience) is the **target node DID** (not a space owner).
+ * - `att` (attenuation) uses the **networkId URN** as the resource
+ *   key (not a `tinycloud:pkh:...:<space>` URI).
+ * - `fct` (facts) binds `bodyHash`, `encryptedSymmetricKeyHash`, and
+ *   `receiverPublicKeyHash` so the node can recompute them from the
+ *   POST body.
+ *
+ * Production callers inject a `DecryptInvocationSigner` backed by the
+ * WASM UCAN/session signer. Tests pass a deterministic stub.
+ */
+
+interface CanonicalDecryptRequest {
+    /** The canonical body that the node will hash. */
+    canonicalBody: string;
+    /** Hex sha-256 of the canonical body bytes. */
+    bodyHash: string;
+    /** Hex sha-256 of the receiver public key bytes. */
+    receiverPublicKeyHash: string;
+}
+interface BuildCanonicalDecryptRequestInput {
+    crypto: EncryptionCrypto;
+    body: DecryptRequestBody;
+    receiverPublicKey: Uint8Array;
+}
+/**
+ * Build the canonical body string and its bound hashes for a decrypt
+ * request. The output is what gets POSTed to the node, and what the
+ * node will hash to verify `facts.bodyHash`.
+ */
+declare function buildCanonicalDecryptRequest(input: BuildCanonicalDecryptRequestInput): CanonicalDecryptRequest;
+interface BuildDecryptFactsInput {
+    crypto: EncryptionCrypto;
+    body: DecryptRequestBody;
+    /** Encrypted symmetric key hash from the envelope (already canonical). */
+    encryptedSymmetricKeyHash: string;
+    /** Receiver public key bytes. */
+    receiverPublicKey: Uint8Array;
+    /** Canonical body string used to derive bodyHash. */
+    canonicalBody?: string;
+}
+/**
+ * Build the {@link DecryptInvocationFact} that will be embedded in the
+ * UCAN `fct` field. Hashes are recomputed here so callers cannot drift
+ * from the canonical body without the node noticing.
+ */
+declare function buildDecryptFacts(input: BuildDecryptFactsInput): DecryptInvocationFact;
+/**
+ * Recap-shaped attenuation for the decrypt invocation. The resource
+ * key is the networkId URN; the ability is the long-form
+ * `tinycloud.encryption/decrypt`. This is intentionally distinct from
+ * the existing space-shaped invocation map so callers cannot
+ * accidentally fake a space prefix.
+ */
+declare function buildDecryptAttenuation(networkId: string): Record<string, Record<string, Record<string, never>>>;
+/**
+ * Validate a {@link BuildDecryptInvocationInput} payload — the body
+ * shape, the facts bindings, and the audience contract — without
+ * actually signing. Returns either the input (typed) or a structured
+ * error so callers can short-circuit before calling into WASM.
+ */
+declare function checkDecryptInvocationInput(crypto: EncryptionCrypto, input: BuildDecryptInvocationInput): {
+    ok: true;
+    data: BuildDecryptInvocationInput;
+    canonicalBody: string;
+} | {
+    ok: false;
+    error: EncryptionError;
+};
+/**
+ * Compose the high-level decrypt invocation and hand it to the signer
+ * for UCAN minting. The signer returns the Authorization header value
+ * plus the invocation CID; this function only validates and
+ * orchestrates — it does not perform crypto signing itself.
+ */
+declare function buildDecryptInvocation(crypto: EncryptionCrypto, signer: DecryptInvocationSigner, input: BuildDecryptInvocationInput): Promise<{
+    ok: true;
+    data: BuiltDecryptInvocation;
+} | {
+    ok: false;
+    error: EncryptionError;
+}>;
+
+/**
+ * Decrypt-response verification.
+ *
+ * The node returns the unwrapped symmetric key re-encrypted to the
+ * per-request receiver public key. Before the SDK uses the wrapped
+ * key, it must:
+ *
+ * 1. Verify the node signature over the canonical response (excluding
+ *    the signature field).
+ * 2. Recompute every binding hash and reject any mismatch.
+ * 3. Confirm `targetNode`, `networkId`, `alg`, and `keyVersion` echo
+ *    what the SDK sent.
+ *
+ * After verification, the SDK opens `wrappedKey` with the per-request
+ * receiver private key and uses the resulting symmetric key to
+ * decrypt the inline envelope payload.
+ */
+
+/**
+ * Construct the canonical bytes that the node signed.
+ *
+ * The signature covers the response with `nodeSignature` removed. We
+ * canonicalize and hash the same way the node does so the binding is
+ * stable.
+ */
+declare function canonicalSignedResponse(response: DecryptResponseBody): string;
+interface VerifyDecryptResponseInput {
+    crypto: EncryptionCrypto;
+    request: DecryptRequestBody;
+    facts: DecryptInvocationFact;
+    /** CID of the signed invocation that produced this response. */
+    invocationCid: string;
+    /** Hex bodyHash that was bound in `facts.bodyHash`. */
+    requestBodyHash: string;
+    response: DecryptResponseBody;
+}
+/**
+ * Verify the node's decrypt response. Returns the response on success;
+ * a structured error on signature, binding, or shape failure.
+ */
+declare function verifyDecryptResponse(input: VerifyDecryptResponseInput): {
+    ok: true;
+    data: DecryptResponseBody;
+} | {
+    ok: false;
+    error: EncryptionError;
+};
+/**
+ * After verification, open the response's `wrappedKey` with the
+ * per-request receiver private key and return the symmetric key.
+ */
+declare function openWrappedKey(crypto: EncryptionCrypto, receiverPrivateKey: Uint8Array, response: DecryptResponseBody): Uint8Array;
+
+export { type BuildCanonicalDecryptRequestInput, type BuildDecryptFactsInput, type BuildDecryptInvocationInput, type BuiltDecryptInvocation, type CanonicalDecryptRequest, type CanonicalJson, DECRYPT_ACTION, DECRYPT_FACT_TYPE, DECRYPT_RESULT_TYPE, DEFAULT_ENCRYPTION_ALG, DEFAULT_KEY_VERSION, type DecryptCapabilityProof, type DecryptEnvelopeOptions, type DecryptInvocationFact, type DecryptInvocationSigner, type DecryptRequestBody, type DecryptResponseBody, type DecryptTransport, type DiscoverNetworkInput, type DiscoveredNetwork, type DiscoverySource, ENCRYPTION_NETWORK_URN_PREFIX, ENCRYPTION_SERVICE, ENCRYPTION_SERVICE_SHORT, ENVELOPE_VERSION, type EncryptToNetworkInput, type EncryptToNetworkOptions, type EncryptToNetworkResult, type EncryptionCrypto, type EncryptionError, type EncryptionErrorInput, EncryptionService, type EncryptionServiceConfig, type IEncryptionService, type InlineEncryptedEnvelope, type Json, NETWORK_NAME_PATTERN, type NetworkDescriptor, NetworkIdError, type NodeDescriptorFetcher, type ParsedNetworkId, type RandomReceiverKeyInput, type ReceiverKeyPair, type ReceiverKeySigner, type SignedReceiverKeyInput, type VerifyDecryptResponseInput, type WellKnownDescriptorFetcher, base64Decode, base64Encode, buildCanonicalDecryptRequest, buildDecryptAttenuation, buildDecryptFacts, buildDecryptInvocation, buildNetworkId, canonicalHashHex, canonicalSignedResponse, canonicalize, checkDecryptInvocationInput, decryptEnvelopeWithKey, deriveSignedReceiverKey, discoverNetwork, encryptToNetwork, encryptionError, ensureNetworkUsableForDecrypt, generateRandomReceiverKey, hexDecode, hexEncode, isNetworkId, networkDiscoveryKey, openWrappedKey, parseNetworkId, utf8Decode, utf8Encode, validateEnvelope, verifyDecryptResponse };