@tinycloud/sdk-services 2.2.1-beta.0 → 2.3.0-beta.5

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

@@ -387,6 +387,7 @@ function canonicalHashHex(sha256, value) {
 // src/encryption/networkId.ts
 var URN_PREFIX = "urn:tinycloud:encryption:";
 var NETWORK_NAME_RE = /^[a-z0-9][a-z0-9-]*$/;
+var PKH_EIP155_DID_RE = /^did:pkh:eip155:(\d+):(0x[a-fA-F0-9]{40})$/;
 var NetworkIdError = class extends Error {
   constructor(message) {
     super(message);
@@ -406,20 +407,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 +428,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;
 }
@@ -453,6 +454,22 @@ function isNetworkId(networkId) {
     return false;
   }
 }
+function parsePkhOwnerDid(ownerDid) {
+  const match = ownerDid.match(PKH_EIP155_DID_RE);
+  if (!match) return null;
+  return {
+    chainId: match[1],
+    address: match[2].toLowerCase()
+  };
+}
+function ownerDidMatches(a, b) {
+  const aPkh = parsePkhOwnerDid(a);
+  const bPkh = parsePkhOwnerDid(b);
+  if (aPkh && bPkh) {
+    return aPkh.chainId === bPkh.chainId && aPkh.address === bPkh.address;
+  }
+  return a === b;
+}
 function networkDiscoveryKey(name) {
   if (!NETWORK_NAME_RE.test(name)) {
     throw new NetworkIdError(
@@ -515,27 +532,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 +571,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 +581,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,8 +604,20 @@ async function discoverNetwork(input) {
     })
   };
 }
-function validateDescriptor(descriptor, networkId, principal, name) {
-  if (descriptor.networkId !== networkId) {
+function validateDescriptor(descriptor, networkId, ownerDid, name) {
+  let descriptorNetwork;
+  try {
+    descriptorNetwork = parseNetworkId(descriptor.networkId);
+  } catch (err2) {
+    return {
+      ok: false,
+      error: encryptionError({
+        code: "INVALID_NETWORK_ID",
+        message: `descriptor networkId is malformed: ${err2 instanceof Error ? err2.message : String(err2)}`
+      })
+    };
+  }
+  if (descriptorNetwork.name !== name || !ownerDidMatches(descriptorNetwork.ownerDid, ownerDid)) {
     return {
       ok: false,
       error: encryptionError({
@@ -597,12 +626,13 @@ function validateDescriptor(descriptor, networkId, principal, name) {
       })
     };
   }
-  if (descriptor.principal !== principal) {
+  const descriptorOwnerDid = descriptorOwner(descriptor);
+  if (descriptorOwnerDid === void 0 || !ownerDidMatches(descriptorOwnerDid, ownerDid) || !ownerDidMatches(descriptorOwnerDid, descriptorNetwork.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"
       })
     };
   }
@@ -624,7 +654,20 @@ function validateDescriptor(descriptor, networkId, principal, name) {
       })
     };
   }
-  return { ok: true, data: descriptor };
+  return {
+    ok: true,
+    data: {
+      ...descriptor,
+      ownerDid: descriptorOwnerDid
+    }
+  };
+}
+function descriptorOwner(descriptor) {
+  if (typeof descriptor.ownerDid === "string" && descriptor.ownerDid.length > 0) {
+    return descriptor.ownerDid;
+  }
+  const legacyDescriptor = descriptor;
+  return typeof legacyDescriptor.principal === "string" && legacyDescriptor.principal.length > 0 ? legacyDescriptor.principal : void 0;
 }
 function ensureNetworkUsableForDecrypt(descriptor) {
   if (descriptor.state === "active" || descriptor.state === "rotating") {
@@ -1094,10 +1137,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 } : {}
     });