@tinycloud/sdk-services 3.11.0 → 3.12.0-beta.16

package/dist/encryption/index.d.cts

@@ -1,25 +1,9 @@
-import { B as BaseService } from '../BaseService-O0iyuFLk.cjs';
-import { c as IService, f as Result } from '../types-CSd0RYir.cjs';
-import { N as NetworkDescriptor, n as EncryptionError, I as InlineEncryptedEnvelope, D as DecryptCapabilityProof, j as DecryptResponseBody, E as EncryptionCrypto, h as DecryptInvocationSigner, p as ReceiverKeySigner, R as ReceiverKeyPair, i as DecryptRequestBody, g as DecryptInvocationFact, B as BuildDecryptInvocationInput, a as BuiltDecryptInvocation } from '../types-D4XbIfFJ.cjs';
-export { C as CanonicalJson, b as DECRYPT_ACTION, c as DECRYPT_FACT_TYPE, d as DECRYPT_RESULT_TYPE, e as DEFAULT_ENCRYPTION_ALG, f as DEFAULT_KEY_VERSION, k as ENCRYPTION_SERVICE, l as ENCRYPTION_SERVICE_SHORT, m as ENVELOPE_VERSION, o as EncryptionErrorInput, J as Json, q as base64Decode, r as base64Encode, s as canonicalHashHex, t as canonicalize, u as encryptionError, v as hexDecode, w as hexEncode, x as utf8Decode, y as utf8Encode } from '../types-D4XbIfFJ.cjs';
+import { B as BaseService } from '../BaseService-CdBkfPGE.cjs';
+import { c as IService, f as Result } from '../types-DjAP8dve.cjs';
+import { N as NetworkDescriptor, n as EncryptionError, I as InlineEncryptedEnvelope, D as DecryptCapabilityProof, j as DecryptResponseBody, E as EncryptionCrypto, h as DecryptInvocationSigner, s as ReceiverKeySigner, r as ReceiverKeyPair, i as DecryptRequestBody, g as DecryptInvocationFact, B as BuildDecryptInvocationInput, a as BuiltDecryptInvocation, Z as KeyWrapContext } from '../types-DfqNz9Nu.cjs';
+export { C as CanonicalJson, _ as ColumnFormat, b as DECRYPT_ACTION, c as DECRYPT_FACT_TYPE, d as DECRYPT_RESULT_TYPE, e as DEFAULT_ENCRYPTION_ALG, f as DEFAULT_KEY_VERSION, k as ENCRYPTION_SERVICE, l as ENCRYPTION_SERVICE_SHORT, m as ENVELOPE_VERSION, o as EncryptionErrorInput, J as Json, $ as KEY_WRAP_V2_ALG, a0 as KeyWrapV2Header, a1 as assertKeyWrapAlgorithm, a2 as assertKeyWrapContext, F as base64Decode, G as base64Encode, H as canonicalHashHex, K as canonicalize, a3 as decryptColumn, O as encryptionError, Q as hexDecode, S as hexEncode, a4 as isKeyWrapV2, a5 as openKeyV2, a6 as readKeyWrapV2, a7 as sealKeyV2, W as utf8Decode, X as utf8Encode } from '../types-DfqNz9Nu.cjs';
 export { DecryptTransportResponseError } from '@tinycloud/sdk-services/internal/decrypt-transport-response-error';
 
-/**
- * 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
- *    owner's public space.
- *
- * The node DB is authoritative on conflict; cached records are
- * advisory only.
- */
-
 type DiscoverySource = "node" | "well-known";
 interface DiscoveredNetwork {
     descriptor: NetworkDescriptor;
@@ -45,8 +29,8 @@ interface DiscoverNetworkInput {
     wellKnown?: WellKnownDescriptorFetcher;
 }
 /**
- * Resolve a network descriptor. The node fetcher is preferred; the
- * well-known fallback is used only on transport failure.
+ * Resolve a network descriptor. The node fetcher is preferred. An optional
+ * well-known cache cannot override a typed registry, identity, or transport failure.
  *
  * The returned descriptor is sanity-checked: `networkId`, `ownerDid`,
  * and `name` must agree with the URN, and the public key field must
@@ -85,11 +69,13 @@ declare function ensureNetworkUsableForDecrypt(descriptor: NetworkDescriptor): {
  */
 
 interface EncryptToNetworkOptions {
+    /** Write TCW2 key wraps. Defaults to the service setting, otherwise false. */
+    keyWrapV2?: boolean;
     /** Exact named-key path to bind into the returned envelope. */
     keyPath?: string;
     /** Optional associated authenticated data (bytes). */
     aad?: Uint8Array;
-    /** Ciphersuite override. Defaults to the network's alg. */
+    /** Ciphersuite override; must match the selected key-wrap writer. */
     alg?: string;
     /** Key version override. Defaults to the network's current key version. */
     keyVersion?: number;
@@ -131,6 +117,10 @@ interface IEncryptionService extends IService {
      *
      * The capability proof must root at the network owner DID embedded
      * in the envelope's networkId.
+     *
+     * Unresponsive decrypt transports use DECRYPTION_DEPENDENCY_UNAVAILABLE.
+     * HTTP failure, identity, registry and caller-cancellation classifications
+     * remain distinct; a failed request never returns partial plaintext.
      */
     decryptEnvelope(envelope: InlineEncryptedEnvelope, capabilityProof: DecryptCapabilityProof, options?: DecryptEnvelopeOptions): Promise<Result<Uint8Array, EncryptionError>>;
 }
@@ -168,11 +158,17 @@ interface DecryptTransport {
 }
 
 interface EncryptionServiceConfig {
+    /** Write TCW2 key wraps. Disabled by default. */
+    keyWrapV2?: boolean;
+    /** Require TCW2 incoming network-key wraps, not signed receiver responses. Disabled by default. */
+    requireKeyWrapV2?: boolean;
     crypto: EncryptionCrypto;
     signer: DecryptInvocationSigner;
     transport: DecryptTransport;
     node?: NodeDescriptorFetcher;
     wellKnown?: WellKnownDescriptorFetcher;
+    /** Verified registry destination; overrides descriptor order and caller hints. */
+    resolveTargetNode?: (networkId: string) => Promise<string>;
     /** Bound by an owning service graph to prevent cross-session authority use. */
     assertActive?: () => void;
     [key: string]: unknown;
@@ -281,6 +277,8 @@ interface EncryptToNetworkInput {
     keyVersion?: number;
     /** Caller-supplied envelope metadata. */
     metadata?: Record<string, string>;
+    /** Write TCW2 key wraps. Disabled by default. */
+    keyWrapV2?: boolean;
 }
 interface EncryptToNetworkResult {
     envelope: InlineEncryptedEnvelope;
@@ -297,7 +295,7 @@ declare function encryptToNetwork(crypto: EncryptionCrypto, input: EncryptToNetw
  * 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): {
+declare function validateEnvelope(crypto: EncryptionCrypto, envelope: unknown, requireKeyWrapV2?: boolean): {
     ok: true;
     data: InlineEncryptedEnvelope;
 } | {
@@ -453,8 +451,8 @@ declare function buildDecryptInvocation(crypto: EncryptionCrypto, signer: Decryp
  * 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.
+ * 3. Confirm the target, network, and key version echo the request and
+ *    the returned key-wrap algorithm is supported independently.
  *
  * After verification, the SDK opens `wrappedKey` with the per-request
  * receiver private key and uses the resulting symmetric key to
@@ -494,6 +492,6 @@ declare function verifyDecryptResponse(input: VerifyDecryptResponseInput): {
  * 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;
+declare function openWrappedKey(crypto: EncryptionCrypto, receiverPrivateKey: Uint8Array, response: DecryptResponseBody, expected?: KeyWrapContext): Uint8Array;
 
-export { type BuildCanonicalDecryptRequestInput, type BuildDecryptFactsInput, BuildDecryptInvocationInput, BuiltDecryptInvocation, type CanonicalDecryptRequest, DecryptCapabilityProof, type DecryptEnvelopeOptions, DecryptInvocationFact, DecryptInvocationSigner, DecryptRequestBody, DecryptResponseBody, type DecryptTransport, type DiscoverNetworkInput, type DiscoveredNetwork, type DiscoverySource, ENCRYPTION_NETWORK_URN_PREFIX, type EncryptToNetworkInput, type EncryptToNetworkOptions, type EncryptToNetworkResult, EncryptionCrypto, EncryptionError, EncryptionService, type EncryptionServiceConfig, type IEncryptionService, InlineEncryptedEnvelope, NETWORK_NAME_PATTERN, NetworkDescriptor, NetworkIdError, type NodeDescriptorFetcher, type ParsedEncryptionResource, type ParsedNetworkId, type RandomReceiverKeyInput, ReceiverKeyPair, ReceiverKeySigner, type SignedReceiverKeyInput, type VerifyDecryptResponseInput, type WellKnownDescriptorFetcher, buildCanonicalDecryptRequest, buildDecryptAttenuation, buildDecryptFacts, buildDecryptInvocation, buildNetworkId, canonicalSignedResponse, checkDecryptInvocationInput, decryptEnvelopeWithKey, deriveSignedReceiverKey, discoverNetwork, encryptToNetwork, ensureNetworkUsableForDecrypt, generateRandomReceiverKey, isNetworkId, networkDiscoveryKey, openWrappedKey, parseEncryptionResource, parseNetworkId, validateEnvelope, verifyDecryptResponse };
+export { type BuildCanonicalDecryptRequestInput, type BuildDecryptFactsInput, BuildDecryptInvocationInput, BuiltDecryptInvocation, type CanonicalDecryptRequest, DecryptCapabilityProof, type DecryptEnvelopeOptions, DecryptInvocationFact, DecryptInvocationSigner, DecryptRequestBody, DecryptResponseBody, type DecryptTransport, type DiscoverNetworkInput, type DiscoveredNetwork, type DiscoverySource, ENCRYPTION_NETWORK_URN_PREFIX, type EncryptToNetworkInput, type EncryptToNetworkOptions, type EncryptToNetworkResult, EncryptionCrypto, EncryptionError, EncryptionService, type EncryptionServiceConfig, type IEncryptionService, InlineEncryptedEnvelope, KeyWrapContext, NETWORK_NAME_PATTERN, NetworkDescriptor, NetworkIdError, type NodeDescriptorFetcher, type ParsedEncryptionResource, type ParsedNetworkId, type RandomReceiverKeyInput, ReceiverKeyPair, ReceiverKeySigner, type SignedReceiverKeyInput, type VerifyDecryptResponseInput, type WellKnownDescriptorFetcher, buildCanonicalDecryptRequest, buildDecryptAttenuation, buildDecryptFacts, buildDecryptInvocation, buildNetworkId, canonicalSignedResponse, checkDecryptInvocationInput, decryptEnvelopeWithKey, deriveSignedReceiverKey, discoverNetwork, encryptToNetwork, ensureNetworkUsableForDecrypt, generateRandomReceiverKey, isNetworkId, networkDiscoveryKey, openWrappedKey, parseEncryptionResource, parseNetworkId, validateEnvelope, verifyDecryptResponse };

package/dist/encryption/index.d.ts

@@ -1,25 +1,9 @@
-import { B as BaseService } from '../BaseService-Ma2MwJAd.js';
-import { c as IService, f as Result } from '../types-CSd0RYir.js';
-import { N as NetworkDescriptor, n as EncryptionError, I as InlineEncryptedEnvelope, D as DecryptCapabilityProof, j as DecryptResponseBody, E as EncryptionCrypto, h as DecryptInvocationSigner, p as ReceiverKeySigner, R as ReceiverKeyPair, i as DecryptRequestBody, g as DecryptInvocationFact, B as BuildDecryptInvocationInput, a as BuiltDecryptInvocation } from '../types-Bf91gup6.js';
-export { C as CanonicalJson, b as DECRYPT_ACTION, c as DECRYPT_FACT_TYPE, d as DECRYPT_RESULT_TYPE, e as DEFAULT_ENCRYPTION_ALG, f as DEFAULT_KEY_VERSION, k as ENCRYPTION_SERVICE, l as ENCRYPTION_SERVICE_SHORT, m as ENVELOPE_VERSION, o as EncryptionErrorInput, J as Json, q as base64Decode, r as base64Encode, s as canonicalHashHex, t as canonicalize, u as encryptionError, v as hexDecode, w as hexEncode, x as utf8Decode, y as utf8Encode } from '../types-Bf91gup6.js';
+import { B as BaseService } from '../BaseService-BRDG69KR.js';
+import { c as IService, f as Result } from '../types-DjAP8dve.js';
+import { N as NetworkDescriptor, n as EncryptionError, I as InlineEncryptedEnvelope, D as DecryptCapabilityProof, j as DecryptResponseBody, E as EncryptionCrypto, h as DecryptInvocationSigner, s as ReceiverKeySigner, r as ReceiverKeyPair, i as DecryptRequestBody, g as DecryptInvocationFact, B as BuildDecryptInvocationInput, a as BuiltDecryptInvocation, Z as KeyWrapContext } from '../types-Nvi_RckJ.js';
+export { C as CanonicalJson, _ as ColumnFormat, b as DECRYPT_ACTION, c as DECRYPT_FACT_TYPE, d as DECRYPT_RESULT_TYPE, e as DEFAULT_ENCRYPTION_ALG, f as DEFAULT_KEY_VERSION, k as ENCRYPTION_SERVICE, l as ENCRYPTION_SERVICE_SHORT, m as ENVELOPE_VERSION, o as EncryptionErrorInput, J as Json, $ as KEY_WRAP_V2_ALG, a0 as KeyWrapV2Header, a1 as assertKeyWrapAlgorithm, a2 as assertKeyWrapContext, F as base64Decode, G as base64Encode, H as canonicalHashHex, K as canonicalize, a3 as decryptColumn, O as encryptionError, Q as hexDecode, S as hexEncode, a4 as isKeyWrapV2, a5 as openKeyV2, a6 as readKeyWrapV2, a7 as sealKeyV2, W as utf8Decode, X as utf8Encode } from '../types-Nvi_RckJ.js';
 export { DecryptTransportResponseError } from '@tinycloud/sdk-services/internal/decrypt-transport-response-error';
 
-/**
- * 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
- *    owner's public space.
- *
- * The node DB is authoritative on conflict; cached records are
- * advisory only.
- */
-
 type DiscoverySource = "node" | "well-known";
 interface DiscoveredNetwork {
     descriptor: NetworkDescriptor;
@@ -45,8 +29,8 @@ interface DiscoverNetworkInput {
     wellKnown?: WellKnownDescriptorFetcher;
 }
 /**
- * Resolve a network descriptor. The node fetcher is preferred; the
- * well-known fallback is used only on transport failure.
+ * Resolve a network descriptor. The node fetcher is preferred. An optional
+ * well-known cache cannot override a typed registry, identity, or transport failure.
  *
  * The returned descriptor is sanity-checked: `networkId`, `ownerDid`,
  * and `name` must agree with the URN, and the public key field must
@@ -85,11 +69,13 @@ declare function ensureNetworkUsableForDecrypt(descriptor: NetworkDescriptor): {
  */
 
 interface EncryptToNetworkOptions {
+    /** Write TCW2 key wraps. Defaults to the service setting, otherwise false. */
+    keyWrapV2?: boolean;
     /** Exact named-key path to bind into the returned envelope. */
     keyPath?: string;
     /** Optional associated authenticated data (bytes). */
     aad?: Uint8Array;
-    /** Ciphersuite override. Defaults to the network's alg. */
+    /** Ciphersuite override; must match the selected key-wrap writer. */
     alg?: string;
     /** Key version override. Defaults to the network's current key version. */
     keyVersion?: number;
@@ -131,6 +117,10 @@ interface IEncryptionService extends IService {
      *
      * The capability proof must root at the network owner DID embedded
      * in the envelope's networkId.
+     *
+     * Unresponsive decrypt transports use DECRYPTION_DEPENDENCY_UNAVAILABLE.
+     * HTTP failure, identity, registry and caller-cancellation classifications
+     * remain distinct; a failed request never returns partial plaintext.
      */
     decryptEnvelope(envelope: InlineEncryptedEnvelope, capabilityProof: DecryptCapabilityProof, options?: DecryptEnvelopeOptions): Promise<Result<Uint8Array, EncryptionError>>;
 }
@@ -168,11 +158,17 @@ interface DecryptTransport {
 }
 
 interface EncryptionServiceConfig {
+    /** Write TCW2 key wraps. Disabled by default. */
+    keyWrapV2?: boolean;
+    /** Require TCW2 incoming network-key wraps, not signed receiver responses. Disabled by default. */
+    requireKeyWrapV2?: boolean;
     crypto: EncryptionCrypto;
     signer: DecryptInvocationSigner;
     transport: DecryptTransport;
     node?: NodeDescriptorFetcher;
     wellKnown?: WellKnownDescriptorFetcher;
+    /** Verified registry destination; overrides descriptor order and caller hints. */
+    resolveTargetNode?: (networkId: string) => Promise<string>;
     /** Bound by an owning service graph to prevent cross-session authority use. */
     assertActive?: () => void;
     [key: string]: unknown;
@@ -281,6 +277,8 @@ interface EncryptToNetworkInput {
     keyVersion?: number;
     /** Caller-supplied envelope metadata. */
     metadata?: Record<string, string>;
+    /** Write TCW2 key wraps. Disabled by default. */
+    keyWrapV2?: boolean;
 }
 interface EncryptToNetworkResult {
     envelope: InlineEncryptedEnvelope;
@@ -297,7 +295,7 @@ declare function encryptToNetwork(crypto: EncryptionCrypto, input: EncryptToNetw
  * 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): {
+declare function validateEnvelope(crypto: EncryptionCrypto, envelope: unknown, requireKeyWrapV2?: boolean): {
     ok: true;
     data: InlineEncryptedEnvelope;
 } | {
@@ -453,8 +451,8 @@ declare function buildDecryptInvocation(crypto: EncryptionCrypto, signer: Decryp
  * 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.
+ * 3. Confirm the target, network, and key version echo the request and
+ *    the returned key-wrap algorithm is supported independently.
  *
  * After verification, the SDK opens `wrappedKey` with the per-request
  * receiver private key and uses the resulting symmetric key to
@@ -494,6 +492,6 @@ declare function verifyDecryptResponse(input: VerifyDecryptResponseInput): {
  * 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;
+declare function openWrappedKey(crypto: EncryptionCrypto, receiverPrivateKey: Uint8Array, response: DecryptResponseBody, expected?: KeyWrapContext): Uint8Array;
 
-export { type BuildCanonicalDecryptRequestInput, type BuildDecryptFactsInput, BuildDecryptInvocationInput, BuiltDecryptInvocation, type CanonicalDecryptRequest, DecryptCapabilityProof, type DecryptEnvelopeOptions, DecryptInvocationFact, DecryptInvocationSigner, DecryptRequestBody, DecryptResponseBody, type DecryptTransport, type DiscoverNetworkInput, type DiscoveredNetwork, type DiscoverySource, ENCRYPTION_NETWORK_URN_PREFIX, type EncryptToNetworkInput, type EncryptToNetworkOptions, type EncryptToNetworkResult, EncryptionCrypto, EncryptionError, EncryptionService, type EncryptionServiceConfig, type IEncryptionService, InlineEncryptedEnvelope, NETWORK_NAME_PATTERN, NetworkDescriptor, NetworkIdError, type NodeDescriptorFetcher, type ParsedEncryptionResource, type ParsedNetworkId, type RandomReceiverKeyInput, ReceiverKeyPair, ReceiverKeySigner, type SignedReceiverKeyInput, type VerifyDecryptResponseInput, type WellKnownDescriptorFetcher, buildCanonicalDecryptRequest, buildDecryptAttenuation, buildDecryptFacts, buildDecryptInvocation, buildNetworkId, canonicalSignedResponse, checkDecryptInvocationInput, decryptEnvelopeWithKey, deriveSignedReceiverKey, discoverNetwork, encryptToNetwork, ensureNetworkUsableForDecrypt, generateRandomReceiverKey, isNetworkId, networkDiscoveryKey, openWrappedKey, parseEncryptionResource, parseNetworkId, validateEnvelope, verifyDecryptResponse };
+export { type BuildCanonicalDecryptRequestInput, type BuildDecryptFactsInput, BuildDecryptInvocationInput, BuiltDecryptInvocation, type CanonicalDecryptRequest, DecryptCapabilityProof, type DecryptEnvelopeOptions, DecryptInvocationFact, DecryptInvocationSigner, DecryptRequestBody, DecryptResponseBody, type DecryptTransport, type DiscoverNetworkInput, type DiscoveredNetwork, type DiscoverySource, ENCRYPTION_NETWORK_URN_PREFIX, type EncryptToNetworkInput, type EncryptToNetworkOptions, type EncryptToNetworkResult, EncryptionCrypto, EncryptionError, EncryptionService, type EncryptionServiceConfig, type IEncryptionService, InlineEncryptedEnvelope, KeyWrapContext, NETWORK_NAME_PATTERN, NetworkDescriptor, NetworkIdError, type NodeDescriptorFetcher, type ParsedEncryptionResource, type ParsedNetworkId, type RandomReceiverKeyInput, ReceiverKeyPair, ReceiverKeySigner, type SignedReceiverKeyInput, type VerifyDecryptResponseInput, type WellKnownDescriptorFetcher, buildCanonicalDecryptRequest, buildDecryptAttenuation, buildDecryptFacts, buildDecryptInvocation, buildNetworkId, canonicalSignedResponse, checkDecryptInvocationInput, decryptEnvelopeWithKey, deriveSignedReceiverKey, discoverNetwork, encryptToNetwork, ensureNetworkUsableForDecrypt, generateRandomReceiverKey, isNetworkId, networkDiscoveryKey, openWrappedKey, parseEncryptionResource, parseNetworkId, validateEnvelope, verifyDecryptResponse };