@tinycloud/sdk-services 2.2.0 → 2.3.0-beta.2

package/dist/encryption/index.d.cts

@@ -100,12 +100,12 @@ interface InlineEncryptedEnvelope {
 /**
  * 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
+ * `.well-known/encryption/network/<name>` in the owner's account
  * space (a discovery record only).
  */
 interface NetworkDescriptor {
     networkId: string;
-    principal: string;
+    ownerDid: string;
     name: string;
     members: ReadonlyArray<{
         nodeId: string;
@@ -234,7 +234,7 @@ interface ReceiverKeySigner {
 }
 /** Capability proof material accompanying a decrypt invocation. */
 interface DecryptCapabilityProof {
-    /** Delegation chain CIDs rooted at the network principal. */
+    /** Delegation chain CIDs rooted at the network owner DID. */
     proofs: ReadonlyArray<string>;
     /** Optional Authorization header value to use instead of building one. */
     authorization?: string;
@@ -334,7 +334,7 @@ type CanonicalJson = Json;
  *    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.
+ *    owner's public space.
  *
  * The node DB is authoritative on conflict; cached records are
  * advisory only.
@@ -351,16 +351,16 @@ interface NodeDescriptorFetcher {
 }
 interface WellKnownDescriptorFetcher {
     /**
-     * Read the cached well-known descriptor by principal + network name.
+     * Read the cached well-known descriptor by owner DID + network name.
      * Returns null if no record exists or the record is unreadable.
      */
-    fetchWellKnown(principal: string, discoveryKey: string): Promise<NetworkDescriptor | null>;
+    fetchWellKnown(ownerDid: string, discoveryKey: string): Promise<NetworkDescriptor | null>;
 }
 interface DiscoverNetworkInput {
-    /** Either a networkId URN or a bare network name (paired with `principal`). */
+    /** Either a networkId URN or a bare network name (paired with `ownerDid`). */
     identifier: string;
     /** Required when identifier is a bare name. */
-    principal?: string;
+    ownerDid?: string;
     node?: NodeDescriptorFetcher;
     wellKnown?: WellKnownDescriptorFetcher;
 }
@@ -368,7 +368,7 @@ interface DiscoverNetworkInput {
  * 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`,
+ * The returned descriptor is sanity-checked: `networkId`, `ownerDid`,
  * and `name` must agree with the URN, and the public key field must
  * be non-empty.
  */
@@ -431,10 +431,10 @@ interface IEncryptionService extends IService {
      *
      * `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`.
+     * name. The bare name form requires the owner DID to be supplied via
+     * `ownerDid`.
      */
-    discoverNetwork(identifier: string, principal?: string): Promise<Result<NetworkDescriptor, EncryptionError>>;
+    discoverNetwork(identifier: string, ownerDid?: 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).
@@ -447,7 +447,7 @@ interface IEncryptionService extends IService {
      * 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
+     * The capability proof must root at the network owner DID embedded
      * in the envelope's networkId.
      */
     decryptEnvelope(envelope: InlineEncryptedEnvelope, capabilityProof: DecryptCapabilityProof, options?: DecryptEnvelopeOptions): Promise<Result<Uint8Array, EncryptionError>>;
@@ -497,7 +497,7 @@ declare class EncryptionService extends BaseService implements IEncryptionServic
     constructor(config: EncryptionServiceConfig);
     get config(): EncryptionServiceConfig;
     private get crypto();
-    discoverNetwork(identifier: string, principal?: string): Promise<Result<NetworkDescriptor, EncryptionError>>;
+    discoverNetwork(identifier: string, ownerDid?: 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>>;
 }
@@ -505,27 +505,27 @@ declare class EncryptionService extends BaseService implements IEncryptionServic
 /**
  * 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
+ * A network id is `urn:tinycloud:encryption:<ownerDid>:<network>` where
+ * `ownerDid` is the owner's DID 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
+ * The embedded owner DID 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.
+ * the network must root at this owner DID.
  */
 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). */
+    /** Owner DID embedded in the URN (the network's root authority). */
+    ownerDid: string;
+    /** Network label (the suffix after the owner DID). */
     name: string;
 }
 declare class NetworkIdError extends Error {
     constructor(message: string);
 }
 /**
- * Parse a network id string into its principal and name components.
+ * Parse a network id string into its owner DID and name components.
  *
  * Throws {@link NetworkIdError} when the input does not match
  * `urn:tinycloud:encryption:<did>:<name>`, when the embedded DID is
@@ -533,17 +533,17 @@ declare class NetworkIdError extends Error {
  */
 declare function parseNetworkId(networkId: string): ParsedNetworkId;
 /**
- * Construct a network id URN from a principal DID and a network name.
+ * Construct a network id URN from an owner DID and a network name.
  * Validates inputs and throws {@link NetworkIdError} on bad shape.
  */
-declare function buildNetworkId(principal: string, name: string): string;
+declare function buildNetworkId(ownerDid: 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.
+ * an owner's public account-space.
  *
  * Format: `.well-known/encryption/network/<name>`.
  */

package/dist/encryption/index.d.ts

@@ -100,12 +100,12 @@ interface InlineEncryptedEnvelope {
 /**
  * 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
+ * `.well-known/encryption/network/<name>` in the owner's account
  * space (a discovery record only).
  */
 interface NetworkDescriptor {
     networkId: string;
-    principal: string;
+    ownerDid: string;
     name: string;
     members: ReadonlyArray<{
         nodeId: string;
@@ -234,7 +234,7 @@ interface ReceiverKeySigner {
 }
 /** Capability proof material accompanying a decrypt invocation. */
 interface DecryptCapabilityProof {
-    /** Delegation chain CIDs rooted at the network principal. */
+    /** Delegation chain CIDs rooted at the network owner DID. */
     proofs: ReadonlyArray<string>;
     /** Optional Authorization header value to use instead of building one. */
     authorization?: string;
@@ -334,7 +334,7 @@ type CanonicalJson = Json;
  *    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.
+ *    owner's public space.
  *
  * The node DB is authoritative on conflict; cached records are
  * advisory only.
@@ -351,16 +351,16 @@ interface NodeDescriptorFetcher {
 }
 interface WellKnownDescriptorFetcher {
     /**
-     * Read the cached well-known descriptor by principal + network name.
+     * Read the cached well-known descriptor by owner DID + network name.
      * Returns null if no record exists or the record is unreadable.
      */
-    fetchWellKnown(principal: string, discoveryKey: string): Promise<NetworkDescriptor | null>;
+    fetchWellKnown(ownerDid: string, discoveryKey: string): Promise<NetworkDescriptor | null>;
 }
 interface DiscoverNetworkInput {
-    /** Either a networkId URN or a bare network name (paired with `principal`). */
+    /** Either a networkId URN or a bare network name (paired with `ownerDid`). */
     identifier: string;
     /** Required when identifier is a bare name. */
-    principal?: string;
+    ownerDid?: string;
     node?: NodeDescriptorFetcher;
     wellKnown?: WellKnownDescriptorFetcher;
 }
@@ -368,7 +368,7 @@ interface DiscoverNetworkInput {
  * 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`,
+ * The returned descriptor is sanity-checked: `networkId`, `ownerDid`,
  * and `name` must agree with the URN, and the public key field must
  * be non-empty.
  */
@@ -431,10 +431,10 @@ interface IEncryptionService extends IService {
      *
      * `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`.
+     * name. The bare name form requires the owner DID to be supplied via
+     * `ownerDid`.
      */
-    discoverNetwork(identifier: string, principal?: string): Promise<Result<NetworkDescriptor, EncryptionError>>;
+    discoverNetwork(identifier: string, ownerDid?: 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).
@@ -447,7 +447,7 @@ interface IEncryptionService extends IService {
      * 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
+     * The capability proof must root at the network owner DID embedded
      * in the envelope's networkId.
      */
     decryptEnvelope(envelope: InlineEncryptedEnvelope, capabilityProof: DecryptCapabilityProof, options?: DecryptEnvelopeOptions): Promise<Result<Uint8Array, EncryptionError>>;
@@ -497,7 +497,7 @@ declare class EncryptionService extends BaseService implements IEncryptionServic
     constructor(config: EncryptionServiceConfig);
     get config(): EncryptionServiceConfig;
     private get crypto();
-    discoverNetwork(identifier: string, principal?: string): Promise<Result<NetworkDescriptor, EncryptionError>>;
+    discoverNetwork(identifier: string, ownerDid?: 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>>;
 }
@@ -505,27 +505,27 @@ declare class EncryptionService extends BaseService implements IEncryptionServic
 /**
  * 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
+ * A network id is `urn:tinycloud:encryption:<ownerDid>:<network>` where
+ * `ownerDid` is the owner's DID 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
+ * The embedded owner DID 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.
+ * the network must root at this owner DID.
  */
 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). */
+    /** Owner DID embedded in the URN (the network's root authority). */
+    ownerDid: string;
+    /** Network label (the suffix after the owner DID). */
     name: string;
 }
 declare class NetworkIdError extends Error {
     constructor(message: string);
 }
 /**
- * Parse a network id string into its principal and name components.
+ * Parse a network id string into its owner DID and name components.
  *
  * Throws {@link NetworkIdError} when the input does not match
  * `urn:tinycloud:encryption:<did>:<name>`, when the embedded DID is
@@ -533,17 +533,17 @@ declare class NetworkIdError extends Error {
  */
 declare function parseNetworkId(networkId: string): ParsedNetworkId;
 /**
- * Construct a network id URN from a principal DID and a network name.
+ * Construct a network id URN from an owner DID and a network name.
  * Validates inputs and throws {@link NetworkIdError} on bad shape.
  */
-declare function buildNetworkId(principal: string, name: string): string;
+declare function buildNetworkId(ownerDid: 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.
+ * an owner's public account-space.
  *
  * Format: `.well-known/encryption/network/<name>`.
  */

package/dist/encryption/index.js

@@ -406,20 +406,20 @@ function parseNetworkId(networkId) {
   const lastColon = body.lastIndexOf(":");
   if (lastColon <= 0 || lastColon === body.length - 1) {
     throw new NetworkIdError(
-      `networkId missing principal or name segment (got ${JSON.stringify(networkId)})`
+      `networkId missing ownerDid or name segment (got ${JSON.stringify(networkId)})`
     );
   }
-  const principal = body.slice(0, lastColon);
+  const ownerDid = body.slice(0, lastColon);
   const name = body.slice(lastColon + 1);
-  if (!principal.startsWith("did:")) {
+  if (!ownerDid.startsWith("did:")) {
     throw new NetworkIdError(
-      `networkId principal must be a DID (got ${JSON.stringify(principal)})`
+      `networkId ownerDid must be a DID (got ${JSON.stringify(ownerDid)})`
     );
   }
-  const didParts = principal.split(":");
+  const didParts = ownerDid.split(":");
   if (didParts.length < 3 || didParts.some((p) => p.length === 0)) {
     throw new NetworkIdError(
-      `networkId principal is not a well-formed DID (got ${JSON.stringify(principal)})`
+      `networkId ownerDid is not a well-formed DID (got ${JSON.stringify(ownerDid)})`
     );
   }
   if (!NETWORK_NAME_RE.test(name)) {
@@ -427,18 +427,18 @@ function parseNetworkId(networkId) {
       `networkId name ${JSON.stringify(name)} must match ${NETWORK_NAME_RE.source}`
     );
   }
-  return { networkId, principal, name };
+  return { networkId, ownerDid, name };
 }
-function buildNetworkId(principal, name) {
-  if (typeof principal !== "string" || !principal.startsWith("did:")) {
-    throw new NetworkIdError("principal must be a DID");
+function buildNetworkId(ownerDid, name) {
+  if (typeof ownerDid !== "string" || !ownerDid.startsWith("did:")) {
+    throw new NetworkIdError("ownerDid must be a DID");
   }
   if (typeof name !== "string" || !NETWORK_NAME_RE.test(name)) {
     throw new NetworkIdError(
       `network name ${JSON.stringify(name)} must match ${NETWORK_NAME_RE.source}`
     );
   }
-  const networkId = `${URN_PREFIX}${principal}:${name}`;
+  const networkId = `${URN_PREFIX}${ownerDid}:${name}`;
   parseNetworkId(networkId);
   return networkId;
 }
@@ -515,27 +515,27 @@ function toError(error) {
 // src/encryption/discovery.ts
 async function discoverNetwork(input) {
   let networkId;
-  let principal;
+  let ownerDid;
   let name;
   try {
     if (input.identifier.startsWith("urn:tinycloud:encryption:")) {
       const parsed = parseNetworkId(input.identifier);
       networkId = parsed.networkId;
-      principal = parsed.principal;
+      ownerDid = parsed.ownerDid;
       name = parsed.name;
     } else {
-      if (input.principal === void 0) {
+      if (input.ownerDid === void 0) {
         return {
           ok: false,
           error: encryptionError({
             code: "INVALID_INPUT",
-            message: "discoverNetwork requires `principal` when identifier is a bare network name"
+            message: "discoverNetwork requires `ownerDid` when identifier is a bare network name"
           })
         };
       }
-      networkId = `urn:tinycloud:encryption:${input.principal}:${input.identifier}`;
+      networkId = `urn:tinycloud:encryption:${input.ownerDid}:${input.identifier}`;
       const parsed = parseNetworkId(networkId);
-      principal = parsed.principal;
+      ownerDid = parsed.ownerDid;
       name = parsed.name;
     }
   } catch (err2) {
@@ -554,7 +554,7 @@ async function discoverNetwork(input) {
     try {
       const descriptor = await input.node.fetchByNetworkId(networkId);
       if (descriptor !== null) {
-        const validated = validateDescriptor(descriptor, networkId, principal, name);
+        const validated = validateDescriptor(descriptor, networkId, ownerDid, name);
         if (!validated.ok) return validated;
         return { ok: true, data: { descriptor: validated.data, source: "node" } };
       }
@@ -564,11 +564,11 @@ async function discoverNetwork(input) {
   if (input.wellKnown !== void 0) {
     try {
       const descriptor = await input.wellKnown.fetchWellKnown(
-        principal,
+        ownerDid,
         networkDiscoveryKey(name)
       );
       if (descriptor !== null) {
-        const validated = validateDescriptor(descriptor, networkId, principal, name);
+        const validated = validateDescriptor(descriptor, networkId, ownerDid, name);
         if (!validated.ok) return validated;
         return {
           ok: true,
@@ -587,7 +587,7 @@ async function discoverNetwork(input) {
     })
   };
 }
-function validateDescriptor(descriptor, networkId, principal, name) {
+function validateDescriptor(descriptor, networkId, ownerDid, name) {
   if (descriptor.networkId !== networkId) {
     return {
       ok: false,
@@ -597,12 +597,12 @@ function validateDescriptor(descriptor, networkId, principal, name) {
       })
     };
   }
-  if (descriptor.principal !== principal) {
+  if (descriptor.ownerDid !== ownerDid) {
     return {
       ok: false,
       error: encryptionError({
         code: "INVALID_NETWORK_ID",
-        message: "descriptor principal does not match networkId principal"
+        message: "descriptor ownerDid does not match networkId ownerDid"
       })
     };
   }
@@ -982,6 +982,15 @@ function verifyDecryptResponse(input) {
       })
     };
   }
+  if (response.nodeId !== request.targetNode) {
+    return {
+      ok: false,
+      error: encryptionError({
+        code: "RESPONSE_BINDING_MISMATCH",
+        field: "nodeId"
+      })
+    };
+  }
   if (response.alg !== request.alg) {
     return {
       ok: false,
@@ -1085,10 +1094,10 @@ var EncryptionService = class extends BaseService {
   get crypto() {
     return this._config.crypto;
   }
-  async discoverNetwork(identifier, principal) {
+  async discoverNetwork(identifier, ownerDid) {
     const result = await discoverNetwork({
       identifier,
-      ...principal !== void 0 ? { principal } : {},
+      ...ownerDid !== void 0 ? { ownerDid } : {},
       ...this._config.node !== void 0 ? { node: this._config.node } : {},
       ...this._config.wellKnown !== void 0 ? { wellKnown: this._config.wellKnown } : {}
     });
@@ -1126,6 +1135,14 @@ var EncryptionService = class extends BaseService {
     try {
       const validated = validateEnvelope(this.crypto, envelope);
       if (!validated.ok) return validated;
+      if (options?.aad !== void 0 && validated.data.aad !== base64Encode(options.aad)) {
+        return encErr(
+          encryptionError({
+            code: "INVALID_INPUT",
+            message: "decryptEnvelope aad does not match the envelope"
+          })
+        );
+      }
       let descriptor;
       if (options?.descriptor !== void 0) {
         descriptor = options.descriptor;