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

package/dist/{types-Bf91gup6.d.ts → types-Nvi_RckJ.d.ts}

@@ -1,4 +1,96 @@
-import { P as PermissionHint } from './types-CSd0RYir.js';
+import { F as FetchFunction, e as FetchResponse, S as ServiceSession, P as PermissionHint } from './types-DjAP8dve.js';
+
+type ResourceAccess = "read" | "write" | "host" | "encryption";
+interface ResourceDestination {
+    readonly url: string;
+    readonly nodeDid?: string;
+}
+interface ResourceNodeInfo {
+    readonly nodeId: string;
+    readonly features?: unknown;
+}
+interface ResourceRoutingConfig {
+    resolveResource(resource: string, access: ResourceAccess): Promise<readonly ResourceDestination[]>;
+    bindAudience(authorization: string, nodeDid: string): Promise<string>;
+    /** Defaults to the raw transport's public node identity checks. */
+    verifyDestination?(target: ResourceDestination): Promise<void | ResourceNodeInfo>;
+}
+/** An identity-checked destination bound to one live resource-routing decision. */
+interface ResourceTransportTarget {
+    readonly url: string;
+    readonly nodeDid: string;
+    readonly fetch: FetchFunction;
+    readonly nodeInfo: ResourceNodeInfo;
+    bindAudience(authorization: string): Promise<string>;
+}
+interface ResourceTransportOptions {
+    /** CID-only controls are node-local and must not choose among several destinations. */
+    readonly nodeLocal?: boolean;
+    /** An existing node-bound authority must match the resolved destination. */
+    readonly nodeDid?: string;
+    /** A verified imported grant activates its resources independently, not atomically. */
+    readonly independentResources?: boolean;
+    /** Captured, verified share-session key for its own locally created invocations. */
+    readonly invocationSession?: ServiceSession;
+}
+type ResourceTransport = (resources: readonly {
+    resource: string;
+    access: ResourceAccess;
+}[], send: (target: ResourceTransportTarget) => Promise<FetchResponse>, options?: ResourceTransportOptions) => Promise<FetchResponse>;
+/** Compare both public node identity surfaces before sending a capability. */
+declare function verifyResourceDestination(target: ResourceDestination, fetchFn: FetchFunction): Promise<ResourceNodeInfo | undefined>;
+declare class NodeNotRespondingError extends Error {
+    readonly hosts: readonly string[];
+    readonly cause?: unknown | undefined;
+    readonly code = "NODE_NOT_RESPONDING";
+    constructor(hosts: readonly string[], cause?: unknown | undefined);
+}
+declare class NodeIdentityMismatchError extends Error {
+    readonly url: string;
+    readonly expectedDid: string;
+    readonly actualDid?: string | undefined;
+    readonly code = "NODE_IDENTITY_MISMATCH";
+    constructor(url: string, expectedDid: string, actualDid?: string | undefined);
+}
+declare class ResourceNotRoutedError extends Error {
+    readonly resource: string;
+    readonly code = "RESOURCE_NOT_ROUTED";
+    constructor(resource: string);
+}
+declare class PartialNodeWriteError extends Error {
+    readonly succeeded: readonly string[];
+    readonly failed: readonly {
+        url: string;
+        status?: number;
+        cause?: unknown;
+    }[];
+    readonly code = "PARTIAL_NODE_WRITE";
+    constructor(succeeded: readonly string[], failed: readonly {
+        url: string;
+        status?: number;
+        cause?: unknown;
+    }[]);
+}
+type RoutingFailureCode = "NODE_NOT_RESPONDING" | "DECRYPTION_DEPENDENCY_UNAVAILABLE" | "PARTIAL_NODE_WRITE" | "NODE_IDENTITY_MISMATCH" | "RESOURCE_NOT_ROUTED" | "registry_unavailable" | "node_not_found" | "node_registry_entry_exists";
+interface RoutingFailure {
+    code: RoutingFailureCode;
+    message: string;
+    cause?: Error;
+    meta?: Record<string, unknown>;
+}
+/** Preserve routing failures through service-specific Result/error adapters. */
+declare function routingFailure(error: unknown): RoutingFailure | undefined;
+/** Extract the signed resource without inferring an account for node-local names. */
+declare function routingResourceOf(uri: string): string;
+/** Share target selection and read/write outcomes with resource-specific adapters. */
+declare function routeResourceRequest(resources: readonly {
+    resource: string;
+    access: ResourceAccess;
+}[], routing: Pick<ResourceRoutingConfig, "resolveResource">, send: (target: ResourceDestination) => Promise<FetchResponse>, options?: ResourceTransportOptions): Promise<FetchResponse>;
+/** Route only locally generated data invocations through a captured share session. */
+declare function createResourceTransportInvocationFetch(transport: ResourceTransport, session: ServiceSession): FetchFunction;
+/** Route signed /invoke traffic. Non-invocation endpoints retain their own resource-specific adapters. */
+declare function createResourceRoutingFetch(fetchFn: FetchFunction, routing: ResourceRoutingConfig): FetchFunction;
 
 /**
  * Canonical JSON serialization and content hashing for TinyCloud
@@ -41,6 +133,40 @@ declare function utf8Decode(b: Uint8Array): string;
  */
 declare function canonicalHashHex(sha256: (bytes: Uint8Array) => Uint8Array, value: Json): string;
 
+declare const KEY_WRAP_V2_ALG: "x25519-hkdf-aes256gcm/v2";
+interface KeyWrapContext {
+    purpose: "network-key" | "receiver-key";
+    networkId: string;
+    keyPath: string;
+    keyVersion: number;
+    metadata: Record<string, string>;
+}
+interface KeyWrapV2Header extends KeyWrapContext {
+    v: 2;
+    alg: typeof KEY_WRAP_V2_ALG;
+    kdf: "hkdf-sha256";
+    aead: "aes-256-gcm";
+    salt: string;
+    ephemeralPublicKey: string;
+    recipientPublicKey: string;
+}
+declare function isKeyWrapV2(wrapped: Uint8Array): boolean;
+/** Parse the closed canonical header. Authentication occurs when the node or recipient opens it. */
+declare function readKeyWrapV2(wrapped: Uint8Array): {
+    header: KeyWrapV2Header;
+    aad: Uint8Array;
+    nonce: Uint8Array;
+    ciphertext: Uint8Array;
+};
+declare function assertKeyWrapContext(header: KeyWrapV2Header, expected: KeyWrapContext): void;
+declare function sealKeyV2(recipientPublicKey: Uint8Array, plaintext: Uint8Array, context: KeyWrapContext): Uint8Array;
+declare function openKeyV2(recipientPrivateKey: Uint8Array, wrapped: Uint8Array, expected: KeyWrapContext): Uint8Array;
+/** Match the declared algorithm without falling back after a TCW2 marker. */
+declare function assertKeyWrapAlgorithm(wrapped: Uint8Array, alg: string, requireV2?: boolean): void;
+type ColumnFormat = "encrypted" | "legacy-plaintext";
+/** Stored format, not input bytes, determines whether a column is plaintext. */
+declare function decryptColumn(decrypt: (key: Uint8Array, ciphertext: Uint8Array) => Uint8Array, key: Uint8Array, blob: Uint8Array, expectedFormat: ColumnFormat, strictEncryption?: boolean): Uint8Array;
+
 /**
  * Type definitions for TinyCloud one-of-one encryption.
  *
@@ -95,7 +221,7 @@ interface InlineEncryptedEnvelope {
     ciphertext: string;
     /** Base64-encoded associated data, if any. */
     aad?: string;
-    /** Caller-supplied metadata. Not authenticated against the node. */
+    /** Caller metadata; v2 wraps bind it to the node-authenticated header. */
     metadata?: Record<string, string>;
 }
 /**
@@ -216,13 +342,16 @@ interface EncryptionCrypto {
      * a sealed-box / hpke / x25519+symmetric construction. Implementation
      * is opaque; only the node can unwrap.
      */
-    sealToNetworkKey(networkPublicKey: Uint8Array, symmetricKey: Uint8Array): Uint8Array;
+    sealToNetworkKey(networkPublicKey: Uint8Array, symmetricKey: Uint8Array, options?: {
+        keyWrapV2: boolean;
+        context: KeyWrapContext;
+    }): 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;
+    openWithReceiverKey(receiverPrivateKey: Uint8Array, wrappedKey: Uint8Array, expected?: KeyWrapContext): Uint8Array;
     /**
      * Verify an ed25519 signature over `message` produced by the node
      * identified by `nodeId` (the public-key DID).
@@ -285,7 +414,7 @@ interface DecryptInvocationSigner {
 /**
  * Errors thrown / returned from the encryption module.
  */
-type EncryptionErrorInput = {
+type EncryptionErrorInput = RoutingFailure | {
     code: "NETWORK_NOT_FOUND";
     networkId?: string;
     name?: string;
@@ -330,4 +459,4 @@ declare function encryptionError(input: EncryptionErrorInput): EncryptionError;
 /** Re-export for ergonomic typing of canonical payloads. */
 type CanonicalJson = Json;
 
-export { type BuildDecryptInvocationInput as B, type CanonicalJson as C, type DecryptCapabilityProof as D, type EncryptionCrypto as E, type InlineEncryptedEnvelope as I, type Json as J, type NetworkDescriptor as N, type ReceiverKeyPair as R, type BuiltDecryptInvocation as a, DECRYPT_ACTION as b, DECRYPT_FACT_TYPE as c, DECRYPT_RESULT_TYPE as d, DEFAULT_ENCRYPTION_ALG as e, DEFAULT_KEY_VERSION as f, type DecryptInvocationFact as g, type DecryptInvocationSigner as h, type DecryptRequestBody as i, type DecryptResponseBody as j, ENCRYPTION_SERVICE as k, ENCRYPTION_SERVICE_SHORT as l, ENVELOPE_VERSION as m, type EncryptionError as n, type EncryptionErrorInput as o, type ReceiverKeySigner as p, base64Decode as q, base64Encode as r, canonicalHashHex as s, canonicalize as t, encryptionError as u, hexDecode as v, hexEncode as w, utf8Decode as x, utf8Encode as y };
+export { KEY_WRAP_V2_ALG as $, type ResourceTransportTarget as A, type BuildDecryptInvocationInput as B, type CanonicalJson as C, type DecryptCapabilityProof as D, type EncryptionCrypto as E, base64Decode as F, base64Encode as G, canonicalHashHex as H, type InlineEncryptedEnvelope as I, type Json as J, canonicalize as K, createResourceRoutingFetch as L, createResourceTransportInvocationFetch as M, type NetworkDescriptor as N, encryptionError as O, PartialNodeWriteError as P, hexDecode as Q, type RoutingFailure as R, hexEncode as S, routeResourceRequest as T, routingFailure as U, routingResourceOf as V, utf8Decode as W, utf8Encode as X, verifyResourceDestination as Y, type KeyWrapContext as Z, type ColumnFormat as _, type BuiltDecryptInvocation as a, type KeyWrapV2Header as a0, assertKeyWrapAlgorithm as a1, assertKeyWrapContext as a2, decryptColumn as a3, isKeyWrapV2 as a4, openKeyV2 as a5, readKeyWrapV2 as a6, sealKeyV2 as a7, DECRYPT_ACTION as b, DECRYPT_FACT_TYPE as c, DECRYPT_RESULT_TYPE as d, DEFAULT_ENCRYPTION_ALG as e, DEFAULT_KEY_VERSION as f, type DecryptInvocationFact as g, type DecryptInvocationSigner as h, type DecryptRequestBody as i, type DecryptResponseBody as j, ENCRYPTION_SERVICE as k, ENCRYPTION_SERVICE_SHORT as l, ENVELOPE_VERSION as m, type EncryptionError as n, type EncryptionErrorInput as o, NodeIdentityMismatchError as p, NodeNotRespondingError as q, type ReceiverKeyPair as r, type ReceiverKeySigner as s, type ResourceAccess as t, type ResourceDestination as u, type ResourceNodeInfo as v, ResourceNotRoutedError as w, type ResourceRoutingConfig as x, type ResourceTransport as y, type ResourceTransportOptions as z };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tinycloud/sdk-services",
-  "version": "3.11.0",
+  "version": "3.12.0-beta.16",
   "description": "TinyCloud SDK Services - Platform-agnostic service implementations",
   "author": "TinyCloud, Inc.",
   "license": "EGPL",
@@ -183,6 +183,9 @@
     "typecheck:contract": "tsc --noEmit -p tsconfig.contract.json"
   },
   "dependencies": {
+    "@noble/ciphers": "1.3.0",
+    "@noble/curves": "^1.9.7",
+    "@noble/hashes": "1.8.0",
     "@tinycloud/bootstrap": "2.8.0",
     "zod": "^3.23.0"
   },