@tinycloud/share-sdk 1.2.0-beta.1 → 1.2.0-beta.2

package/dist/share-root.js

@@ -5428,6 +5428,37 @@ function serialize(value) {
 function canonicalize(value) {
   return serialize(value);
 }
+async function signCompactUcanAuthorization(input) {
+  if (input.notBefore >= input.expiresAt || input.expiresAt - input.notBefore > 60) {
+    throw new TypeError("compact invocation lifetime must be between one and 60 seconds");
+  }
+  const principal = input.issuerDid.split("#", 1)[0];
+  const publicKey = ed25519PublicKeyFromDidKey(principal);
+  const header = {
+    alg: "EdDSA",
+    jwk: { alg: "EdDSA", crv: "Ed25519", kty: "OKP", x: toBase64Url(publicKey) },
+    typ: "JWT",
+    ucv: "0.10.0"
+  };
+  const payload = {
+    att: input.attenuation,
+    aud: input.audienceDid,
+    exp: input.expiresAt,
+    fct: input.facts,
+    iss: input.issuerDid.includes("#") ? input.issuerDid : `${principal}#${principal.slice("did:key:".length)}`,
+    nbf: input.notBefore,
+    nnc: input.nonce,
+    prf: input.proofs
+  };
+  const protectedSegment = toBase64Url(new TextEncoder().encode(canonicalize(header)));
+  const payloadSegment = toBase64Url(new TextEncoder().encode(canonicalize(payload)));
+  const signingInput = new TextEncoder().encode(`${protectedSegment}.${payloadSegment}`);
+  const signature = await input.sign(signingInput);
+  if (signature.length !== 64) throw new TypeError("compact Authorization signature must be Ed25519");
+  return verifyCompactUcanAuthorization(
+    `${protectedSegment}.${payloadSegment}.${toBase64Url(signature)}`
+  );
+}
 function verifyCompactUcanAuthorization(authorization, expectedCid) {
   if (/\s/.test(authorization)) throw new TypeError("compact Authorization contains whitespace");
   const segments = authorization.split(".");
@@ -6618,44 +6649,57 @@ function parseTime(value, label, rootCid) {
   if (!Number.isFinite(time)) throw new ShareRootError("malformed-root", `share root ${label} is missing or invalid`, { rootCid, mustRevoke: true });
   return time;
 }
-function validateSignedRoot(decoded, expected) {
+function validateSignedOwnerDelegation(decoded, expected) {
+  const { label } = expected;
   const wider = { rootCid: decoded.cid, mustRevoke: true };
   let issuer;
   try {
     issuer = parseOwnerDid(decoded.issuer);
   } catch {
-    throw new ShareRootError("issuer-mismatch", "share root is not signed by a did:pkh owner", wider);
-  }
-  if (!sameOwner(issuer, expected.owner)) throw new ShareRootError("issuer-mismatch", "share root is signed by another owner", wider);
-  if (decoded.audience !== expected.keyDid) throw new ShareRootError("audience-mismatch", "share root is not delegated to the share key", wider);
-  if (decoded.resources.length !== 1 || !decoded.resources[0].startsWith("urn:recap:")) throw new ShareRootError("resource-mismatch", "share root must carry exactly one ReCap resource", wider);
-  if (decoded.reCapProofs.length !== 0) throw new ShareRootError("resource-mismatch", "share root must not have parent capabilities", wider);
-  const wanted = { [`${expected.spaceId}/kv/${SHARE_ROOT_PREFIX}`]: KV_ABILITIES };
-  if (expected.scope === "kv+share-decrypt") wanted[shareNetworkId(expected.owner)] = [DECRYPT_ABILITY];
-  for (const resource of Object.keys(decoded.attenuation)) if (wanted[resource] === void 0) throw new ShareRootError("resource-mismatch", "share root grants a resource outside its scope", wider);
+    throw new ShareRootError("issuer-mismatch", `${label} is not signed by a did:pkh owner`, wider);
+  }
+  if (!sameOwner(issuer, expected.owner)) throw new ShareRootError("issuer-mismatch", `${label} is signed by another owner`, wider);
+  if (decoded.audience !== expected.keyDid) throw new ShareRootError("audience-mismatch", `${label} is not delegated to its key`, wider);
+  if (decoded.resources.length !== 1 || !decoded.resources[0].startsWith("urn:recap:")) throw new ShareRootError("resource-mismatch", `${label} must carry exactly one ReCap resource`, wider);
+  if (decoded.reCapProofs.length !== 0) throw new ShareRootError("resource-mismatch", `${label} must not have parent capabilities`, wider);
+  const { wanted } = expected;
+  for (const resource of Object.keys(decoded.attenuation)) if (wanted[resource] === void 0) throw new ShareRootError("resource-mismatch", `${label} grants a resource outside its scope`, wider);
   for (const [resource, abilities] of Object.entries(wanted)) {
     const granted = decoded.attenuation[resource];
-    if (granted === void 0) throw new ShareRootError("resource-mismatch", "share root is missing one of its resources", wider);
+    if (granted === void 0) throw new ShareRootError("resource-mismatch", `${label} is missing one of its resources`, wider);
     const names = Object.keys(granted);
-    if (names.length !== abilities.length || abilities.some((ability) => !names.includes(ability))) throw new ShareRootError("ability-mismatch", "share root abilities differ from the request", wider);
+    if (names.length !== abilities.length || abilities.some((ability) => !names.includes(ability))) throw new ShareRootError("ability-mismatch", `${label} abilities differ from the request`, wider);
     for (const ability of abilities) {
       const caveats = granted[ability];
       if (caveats.length !== 1 || typeof caveats[0] !== "object" || caveats[0] === null || Array.isArray(caveats[0]) || Object.keys(caveats[0]).length !== 0) {
-        throw new ShareRootError("ability-mismatch", "share root abilities carry unexpected caveats", wider);
+        throw new ShareRootError("ability-mismatch", `${label} abilities carry unexpected caveats`, wider);
       }
     }
   }
   const issuedAt = parseTime(decoded.issuedAt, "issued-at time", decoded.cid);
   const expiresAt = parseTime(decoded.expiresAt, "expiration time", decoded.cid);
-  if (decoded.notBefore !== void 0 && parseTime(decoded.notBefore, "not-before time", decoded.cid) > expected.now) throw new ShareRootError("malformed-root", "share root is not valid yet", { rootCid: decoded.cid });
-  const cap = PROFILES[expected.kind].maxLifetimeMs;
-  if (expiresAt - issuedAt > cap + SHARE_ROOT_CLOCK_SKEW_MS || expiresAt - expected.now > cap) throw new ShareRootError("lifetime-exceeds-cap", `${expected.kind} root lifetime exceeds ${cap / DAY_MS} days`, wider);
-  if (expiresAt <= expected.now) throw new ShareRootError("expired", "share root has expired", { rootCid: decoded.cid });
+  if (decoded.notBefore !== void 0 && parseTime(decoded.notBefore, "not-before time", decoded.cid) > expected.now) throw new ShareRootError("malformed-root", `${label} is not valid yet`, { rootCid: decoded.cid });
+  const cap = expected.maxLifetimeMs;
+  if (expiresAt - issuedAt > cap + SHARE_ROOT_CLOCK_SKEW_MS || expiresAt - expected.now > cap) throw new ShareRootError("lifetime-exceeds-cap", `${label} lifetime exceeds its cap`, wider);
+  if (expiresAt <= expected.now) throw new ShareRootError("expired", `${label} has expired`, { rootCid: decoded.cid });
   if (expected.requestedExpiresAt !== void 0 && seconds(expiresAt) !== seconds(expected.requestedExpiresAt.getTime())) {
-    throw new ShareRootError("expiry-mismatch", "share root was signed with a different expiry than requested", { rootCid: decoded.cid, mustRevoke: expiresAt > expected.requestedExpiresAt.getTime() });
+    throw new ShareRootError("expiry-mismatch", `${label} was signed with a different expiry than requested`, { rootCid: decoded.cid, mustRevoke: expiresAt > expected.requestedExpiresAt.getTime() });
   }
   return { issuedAt: new Date(issuedAt), expiresAt: new Date(expiresAt) };
 }
+function validateSignedRoot(decoded, expected) {
+  const wanted = { [`${expected.spaceId}/kv/${SHARE_ROOT_PREFIX}`]: KV_ABILITIES };
+  if (expected.scope === "kv+share-decrypt") wanted[shareNetworkId(expected.owner)] = [DECRYPT_ABILITY];
+  return validateSignedOwnerDelegation(decoded, {
+    label: `${expected.kind} root`,
+    owner: expected.owner,
+    keyDid: expected.keyDid,
+    wanted,
+    maxLifetimeMs: PROFILES[expected.kind].maxLifetimeMs,
+    ...expected.requestedExpiresAt === void 0 ? {} : { requestedExpiresAt: expected.requestedExpiresAt },
+    now: expected.now
+  });
+}
 function assertLinkPath(path) {
   if (typeof path !== "string" || !path.startsWith(SHARE_ROOT_PREFIX) || path.length === SHARE_ROOT_PREFIX.length || path.endsWith("/") || path.includes("//") || path.split("/").some((segment) => segment === "." || segment === "..") || /[\u0000-\u001f\u007f\\*?#]/.test(path)) throw new ShareRootError("link-out-of-scope", "link path must be one exact key under the share prefix");
 }
@@ -6690,6 +6734,43 @@ function policyRootContents(input) {
   }
   return { facts, attenuation };
 }
+function ownerPolicySigner(input) {
+  const { ownerDid, authorityCid, notAfter, gate } = input;
+  return {
+    ownerDid,
+    rootCid: authorityCid,
+    notAfter,
+    createOwnerRoot: async (root) => {
+      const key = await gate();
+      const now = input.now();
+      const notBefore = root.notBefore instanceof Date ? root.notBefore.getTime() : Number.NaN;
+      const expiry = root.expiresAt instanceof Date ? root.expiresAt.getTime() : Number.NaN;
+      if (root.ownerDid !== ownerDid || root.role !== "policy-authority" && root.role !== "policy-enforcement") throw new ShareRootError("invalid-request", "policy root must be owned by this key");
+      if (!Number.isFinite(notBefore) || !Number.isFinite(expiry) || notBefore >= expiry || expiry <= now) throw new ShareRootError("invalid-request", "policy root validity is invalid");
+      if (expiry > notAfter.getTime() || expiry - notBefore > MAX_POLICY_ROOT_MS) throw new ShareRootError("lifetime-exceeds-cap", "policy root must not outlive its owner delegation or 31 days", { rootCid: authorityCid });
+      for (const capability of root.capabilities) {
+        if (!input.inScope(capability)) throw new ShareRootError("invalid-request", "policy root capability is outside the owner delegation");
+      }
+      const { facts, attenuation } = policyRootContents(root);
+      const signed = await signShareKeyDelegation({
+        key,
+        audienceDid: root.audienceDid,
+        attenuation,
+        facts: [facts],
+        proofs: [],
+        notBefore: seconds(notBefore),
+        expiresAt: seconds(expiry),
+        nonce: toBase64Url(crypto.getRandomValues(new Uint8Array(16)))
+      });
+      return { cid: signed.cid, delegationHeader: { Authorization: signed.authorization } };
+    },
+    sign: async (digest) => {
+      const key = await gate();
+      if (!(digest instanceof Uint8Array) || digest.length !== 32) throw new ShareRootError("invalid-request", "policy signer signs 32-byte digests only");
+      return key.sign(digest);
+    }
+  };
+}
 function readPolicyOwnerAuthorityMode(features) {
   if (!Array.isArray(features) || !features.includes(POLICY_OWNER_AUTHORITY_FEATURES.marker)) return void 0;
   const enforce = features.includes(POLICY_OWNER_AUTHORITY_FEATURES.enforce);
@@ -6912,44 +6993,15 @@ var ShareRoot = class _ShareRoot {
    */
   async policyRootSigner() {
     await this.#assertPolicyGate();
-    const gate = () => this.#assertPolicyGate();
     const owner = parseOwnerDid(this.ownerDid);
-    const notAfter = new Date(this.expiresAt);
-    return {
+    return ownerPolicySigner({
       ownerDid: this.keyDid,
-      rootCid: this.cid,
-      notAfter,
-      createOwnerRoot: async (input) => {
-        const key = await gate();
-        const now = this.#now();
-        const notBefore = input.notBefore instanceof Date ? input.notBefore.getTime() : Number.NaN;
-        const expiry = input.expiresAt instanceof Date ? input.expiresAt.getTime() : Number.NaN;
-        if (input.ownerDid !== this.keyDid || input.role !== "policy-authority" && input.role !== "policy-enforcement") throw new ShareRootError("invalid-request", "policy root must be owned by this share key");
-        if (!Number.isFinite(notBefore) || !Number.isFinite(expiry) || notBefore >= expiry || expiry <= now) throw new ShareRootError("invalid-request", "policy root validity is invalid");
-        if (expiry > notAfter.getTime() || expiry - notBefore > MAX_POLICY_ROOT_MS) throw new ShareRootError("lifetime-exceeds-cap", "policy root must not outlive its share root or 31 days", { rootCid: this.cid });
-        for (const capability of input.capabilities) {
-          const inScope = capability.kind === "encryption" ? isShareNetworkOf(capability.resource, owner) && capability.action === DECRYPT_ABILITY : capability.resource.startsWith(`${this.spaceId}/kv/${SHARE_ROOT_PREFIX}`) && capability.actions.every((action) => KV_ABILITIES.includes(action));
-          if (!inScope) throw new ShareRootError("invalid-request", "policy root capability is outside the share root");
-        }
-        const { facts, attenuation } = policyRootContents(input);
-        const root = await signShareKeyDelegation({
-          key,
-          audienceDid: input.audienceDid,
-          attenuation,
-          facts: [facts],
-          proofs: [],
-          notBefore: seconds(notBefore),
-          expiresAt: seconds(expiry),
-          nonce: toBase64Url(crypto.getRandomValues(new Uint8Array(16)))
-        });
-        return { cid: root.cid, delegationHeader: { Authorization: root.authorization } };
-      },
-      sign: async (digest) => {
-        const key = await gate();
-        if (!(digest instanceof Uint8Array) || digest.length !== 32) throw new ShareRootError("invalid-request", "policy signer signs 32-byte digests only");
-        return key.sign(digest);
-      }
-    };
+      authorityCid: this.cid,
+      notAfter: new Date(this.expiresAt),
+      gate: () => this.#assertPolicyGate(),
+      now: () => this.#now(),
+      inScope: (capability) => capability.kind === "encryption" ? isShareNetworkOf(capability.resource, owner) && capability.action === DECRYPT_ABILITY : capability.resource.startsWith(`${this.spaceId}/kv/${SHARE_ROOT_PREFIX}`) && capability.actions.every((action) => KV_ABILITIES.includes(action))
+    });
   }
   /** Drop this root's key handle. It does not revoke the root: only the owner does that. */
   clear() {
@@ -7007,6 +7059,274 @@ async function ensureShareRoot(input) {
   }
   return { root, rerooted: true };
 }
+
+// src/share-grant.ts
+var ACTIONS = {
+  view: ["tinycloud.kv/get", "tinycloud.kv/metadata"],
+  edit: ["tinycloud.kv/get", "tinycloud.kv/metadata", "tinycloud.kv/put"]
+};
+function wantedFor(spaceId, path, access, owner) {
+  return { [`${spaceId}/kv/${path}`]: ACTIONS[access], [shareNetworkId(owner)]: [DECRYPT_ABILITY] };
+}
+var ShareGrant = class _ShareGrant {
+  cid;
+  ownerDid;
+  spaceId;
+  keyDid;
+  nodeOrigin;
+  path;
+  access;
+  issuedAt;
+  expiresAt;
+  #authorization;
+  #key;
+  #now;
+  constructor(input) {
+    this.cid = input.cid;
+    this.ownerDid = input.ownerDid;
+    this.spaceId = input.spaceId;
+    this.keyDid = input.key.did;
+    this.nodeOrigin = input.nodeOrigin;
+    this.path = input.path;
+    this.access = input.access;
+    this.issuedAt = input.issuedAt;
+    this.expiresAt = input.expiresAt;
+    this.#authorization = input.authorization;
+    this.#key = input.key;
+    this.#now = input.now;
+  }
+  /**
+   * Ask the owner for one per-share grant (one approval). Path, access,
+   * expiry, space and Node origin are checked before the wallet is asked; the
+   * signed CACAO is decoded and must match exactly, or the key is cleared and
+   * the error carries the imported CID (`mustRevoke` when it may be wider).
+   */
+  static async create(input) {
+    const clock = input.now ?? Date.now;
+    const now = clock();
+    const owner = parseOwnerDid(input.owner.ownerDid);
+    assertSpace(input.spaceId, owner, "share");
+    const nodeOrigin = requireNodeOrigin(input.nodeOrigin);
+    assertLinkPath(input.path);
+    if (input.access !== "view" && input.access !== "edit") throw new ShareRootError("invalid-request", "share grant access must be view or edit");
+    const expiry = input.expiresAt instanceof Date ? input.expiresAt.getTime() : Number.NaN;
+    if (!Number.isFinite(expiry) || expiry <= now) throw new ShareRootError("invalid-request", "share grant expiry must be in the future");
+    if (expiry - now > SHARE_ROOT_LINK_MAX_LIFETIME_MS) throw new ShareRootError("lifetime-exceeds-cap", "share grant lifetime exceeds 30 days");
+    const key = await (input.keyFactory ?? (() => createDelegatedShareKey({ extractable: false })))();
+    try {
+      await assertUsableKey(key);
+    } catch (error) {
+      key.clear();
+      throw error;
+    }
+    const permissions = [
+      { service: "tinycloud.kv", path: input.path, actions: [...ACTIONS[input.access]] },
+      { service: "tinycloud.encryption", path: shareNetworkId(owner), actions: [DECRYPT_ABILITY] }
+    ];
+    let receipt;
+    try {
+      receipt = await input.owner.createOwnerDelegation({ delegateDid: key.did, spaceId: input.spaceId, expiresAt: input.expiresAt, permissions });
+    } catch (error) {
+      key.clear();
+      throw error;
+    }
+    try {
+      const authorization = new Uint8Array(receipt.signedDagCbor);
+      const signedCid = ownerRootCacaoCid(authorization);
+      if (signedCid !== receipt.delegationCid) throw new ShareRootError("malformed-root", "signed grant bytes do not match the imported delegation CID", { rootCid: receipt.delegationCid, signedCid, mustRevoke: true });
+      let decoded;
+      try {
+        decoded = decodeOwnerRootCacao(authorization);
+      } catch (error) {
+        throw new ShareRootError("malformed-root", errorMessage(error), { rootCid: receipt.delegationCid, mustRevoke: true });
+      }
+      const times = validateSignedOwnerDelegation(decoded, {
+        label: "per-share grant",
+        owner,
+        keyDid: key.did,
+        wanted: wantedFor(input.spaceId, input.path, input.access, owner),
+        maxLifetimeMs: SHARE_ROOT_LINK_MAX_LIFETIME_MS,
+        requestedExpiresAt: input.expiresAt,
+        now: clock()
+      });
+      return new _ShareGrant({ cid: decoded.cid, ownerDid: input.owner.ownerDid, spaceId: input.spaceId, nodeOrigin, path: input.path, access: input.access, ...times, authorization, key, now: clock });
+    } catch (error) {
+      key.clear();
+      if (error instanceof ShareRootError) throw error;
+      throw new ShareRootError("malformed-root", errorMessage(error), { rootCid: receipt.delegationCid, mustRevoke: true });
+    }
+  }
+  /** Rebuild a stored grant with its key (e.g. a CLI 0600 key file); the signed bytes are checked again. */
+  static async restore(input) {
+    const { record } = input;
+    const clock = input.now ?? Date.now;
+    if (record.version !== 1 || record.access !== "view" && record.access !== "edit") throw new ShareRootError("malformed-root", "share grant record is not supported");
+    if (record.keyDid !== input.key.did) throw new ShareRootError("audience-mismatch", "share grant record belongs to another key");
+    const owner = parseOwnerDid(record.ownerDid);
+    assertSpace(record.spaceId, owner, "share");
+    const nodeOrigin = requireNodeOrigin(record.nodeOrigin);
+    assertLinkPath(record.path);
+    await assertUsableKey(input.key);
+    let authorization;
+    let decoded;
+    try {
+      authorization = fromBase64Url(record.authorization);
+      decoded = decodeOwnerRootCacao(authorization, record.cid);
+    } catch (error) {
+      throw new ShareRootError("malformed-root", errorMessage(error), { rootCid: record.cid });
+    }
+    const times = validateSignedOwnerDelegation(decoded, {
+      label: "per-share grant",
+      owner,
+      keyDid: input.key.did,
+      wanted: wantedFor(record.spaceId, record.path, record.access, owner),
+      maxLifetimeMs: SHARE_ROOT_LINK_MAX_LIFETIME_MS,
+      now: clock()
+    });
+    return new _ShareGrant({ cid: decoded.cid, ownerDid: record.ownerDid, spaceId: record.spaceId, nodeOrigin, path: record.path, access: record.access, ...times, authorization, key: input.key, now: clock });
+  }
+  /** The `Authorization` value the Node knows this grant by (base64url CACAO). */
+  get authorization() {
+    return toBase64Url(this.#authorization);
+  }
+  /** The exact KV resource this grant covers. */
+  get resource() {
+    return `${this.spaceId}/kv/${this.path}`;
+  }
+  toRecord() {
+    return { version: 1, cid: this.cid, authorization: this.authorization, spaceId: this.spaceId, ownerDid: this.ownerDid, keyDid: this.keyDid, nodeOrigin: this.nodeOrigin, path: this.path, access: this.access, expiresAt: this.expiresAt.toISOString() };
+  }
+  /**
+   * Policy/v3 owner signing for this one share. Every call checks the key is
+   * held and the grant is live. Policy roots must be owned by the per-share
+   * key, expire no later than the grant, and name only this grant's exact
+   * KV resource (with no action the grant lacks) and decrypt on `:share`.
+   */
+  policySigner() {
+    const owner = parseOwnerDid(this.ownerDid);
+    const actions = ACTIONS[this.access];
+    return ownerPolicySigner({
+      ownerDid: this.keyDid,
+      authorityCid: this.cid,
+      notAfter: new Date(this.expiresAt),
+      gate: async () => this.#activeKey(),
+      now: this.#now,
+      inScope: (capability) => capability.kind === "encryption" ? isShareNetworkOf(capability.resource, owner) && capability.action === DECRYPT_ABILITY : capability.resource === this.resource && capability.selector === "exact" && capability.actions.every((action) => actions.includes(action))
+    });
+  }
+  /** `publishAddressedShare`'s `authority` for this share: the policy signer plus the caller's `registerPolicy`. */
+  publishAuthority(registerPolicy) {
+    return { ...this.policySigner(), registerPolicy };
+  }
+  /** Drop the per-share key. It does not revoke the grant: only the owner does that. */
+  clear() {
+    this.#key?.clear();
+    this.#key = void 0;
+  }
+  #activeKey() {
+    if (this.#key === void 0) throw new ShareRootError("key-cleared", "share grant key has been cleared", { rootCid: this.cid });
+    if (this.#now() >= this.expiresAt.getTime()) throw new ShareRootError("expired", "share grant has expired", { rootCid: this.cid });
+    return this.#key;
+  }
+};
+
+// src/share-network.ts
+import { sha256 as sha2564 } from "@noble/hashes/sha256";
+var NETWORK_CREATE_ABILITY = "tinycloud.encryption/network.create";
+var NETWORK_ADMIN_TYPE = "tinycloud.encryption.network-admin/v1";
+var NETWORK_GRANT_LIFETIME_MS = 10 * 6e4;
+function shareNetworkIdFor(ownerDid) {
+  parseOwnerDid(ownerDid);
+  return `urn:tinycloud:encryption:${ownerDid}:share`;
+}
+function hex(bytes2) {
+  return [...bytes2].map((byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+async function existingShareNetwork(nodeOrigin, networkId, ownerDid, fetchFn) {
+  const response = await fetchFn(new URL(`/encryption/networks/${encodeURIComponent(networkId)}`, nodeOrigin), { redirect: "error" });
+  if (response.status === 404) return void 0;
+  if (!response.ok) throw new ShareRootError("invalid-request", `share network lookup failed: HTTP ${response.status}`);
+  const body = await response.json();
+  const descriptor = typeof body === "object" && body !== null && "descriptor" in body ? body.descriptor : body;
+  if (typeof descriptor !== "object" || descriptor === null || !("networkId" in descriptor) || !("ownerDid" in descriptor) || !("state" in descriptor)) {
+    throw new ShareRootError("invalid-request", "share network descriptor is malformed");
+  }
+  const { networkId: foundId, ownerDid: foundOwner, state } = descriptor;
+  const owner = parseOwnerDid(ownerDid);
+  if (typeof foundId !== "string" || !isShareNetworkOf(foundId, owner) || typeof foundOwner !== "string" || !sameOwner(parseOwnerDid(foundOwner), owner)) {
+    throw new ShareRootError("invalid-request", "share network is not owned by this owner");
+  }
+  if (state === "revoked" || state === "failed") throw new ShareRootError("invalid-request", `share network is ${String(state)}`);
+  return foundId;
+}
+async function ensureShareNetwork(input) {
+  const clock = input.now ?? Date.now;
+  const fetchFn = input.fetch ?? ((url, init) => globalThis.fetch(url, init));
+  const owner = parseOwnerDid(input.owner.ownerDid);
+  assertSpace(input.spaceId, owner, "share");
+  const nodeOrigin = requireNodeOrigin(input.nodeOrigin);
+  const networkId = shareNetworkIdFor(input.owner.ownerDid);
+  const existing = await existingShareNetwork(nodeOrigin, networkId, input.owner.ownerDid, fetchFn);
+  if (existing !== void 0) return { networkId: existing, approvals: 0 };
+  const info = await (await fetchFn(new URL("/info", nodeOrigin), { redirect: "error" })).json();
+  const nodeDid = typeof info === "object" && info !== null && "nodeId" in info ? info.nodeId : void 0;
+  if (typeof nodeDid !== "string" || !nodeDid.startsWith("did:key:")) throw new ShareRootError("invalid-request", "node identity is unavailable");
+  const key = await (input.keyFactory ?? (() => createDelegatedShareKey({ extractable: false })))();
+  try {
+    await assertUsableKey(key);
+    const expiresAt = new Date(clock() + NETWORK_GRANT_LIFETIME_MS);
+    const receipt = await input.owner.createOwnerDelegation({
+      delegateDid: key.did,
+      spaceId: input.spaceId,
+      expiresAt,
+      permissions: [{ service: "tinycloud.encryption", path: networkId, actions: [NETWORK_CREATE_ABILITY] }]
+    });
+    const authorization = new Uint8Array(receipt.signedDagCbor);
+    const signedCid = ownerRootCacaoCid(authorization);
+    if (signedCid !== receipt.delegationCid) throw new ShareRootError("malformed-root", "signed network grant bytes do not match the imported delegation CID", { rootCid: receipt.delegationCid, signedCid, mustRevoke: true });
+    let decoded;
+    try {
+      decoded = decodeOwnerRootCacao(authorization);
+    } catch (error) {
+      throw new ShareRootError("malformed-root", errorMessage(error), { rootCid: receipt.delegationCid, mustRevoke: true });
+    }
+    validateSignedOwnerDelegation(decoded, {
+      label: "share network grant",
+      owner,
+      keyDid: key.did,
+      wanted: { [networkId]: [NETWORK_CREATE_ABILITY] },
+      maxLifetimeMs: NETWORK_GRANT_LIFETIME_MS,
+      requestedExpiresAt: expiresAt,
+      now: clock()
+    });
+    const body = { name: "share", ownerDid: input.owner.ownerDid, threshold: { n: 1, t: 1 } };
+    const canonicalBody = canonicalize(body);
+    const now = seconds(clock());
+    const invocation = await signCompactUcanAuthorization({
+      issuerDid: key.did,
+      audienceDid: nodeDid,
+      attenuation: { [networkId]: { [NETWORK_CREATE_ABILITY]: [{}] } },
+      facts: [{ type: NETWORK_ADMIN_TYPE, targetNode: nodeDid, networkId, bodyHash: hex(sha2564(new TextEncoder().encode(canonicalBody))), action: NETWORK_CREATE_ABILITY }],
+      proofs: [decoded.cid],
+      notBefore: now,
+      expiresAt: now + 60,
+      nonce: toBase64Url(crypto.getRandomValues(new Uint8Array(16))),
+      sign: (bytes2) => key.sign(bytes2)
+    });
+    const response = await fetchFn(new URL("/encryption/networks", nodeOrigin), {
+      method: "POST",
+      redirect: "error",
+      headers: { Authorization: invocation.authorization, "content-type": "application/json" },
+      body: canonicalBody
+    });
+    if (!response.ok && response.status !== 409) throw new ShareRootError("invalid-request", `share network creation failed: HTTP ${response.status} ${(await response.text()).slice(0, 120)}`);
+    const created = await existingShareNetwork(nodeOrigin, networkId, input.owner.ownerDid, fetchFn);
+    if (created === void 0) throw new ShareRootError("invalid-request", "share network was not created");
+    return { networkId: created, approvals: 1 };
+  } finally {
+    key.clear();
+  }
+}
 export {
   AGENT_SHARE_ROOT_MAX_LIFETIME_MS,
   POLICY_OWNER_AUTHORITY_FEATURES,
@@ -7016,15 +7336,18 @@ export {
   SHARE_ROOT_MAX_LIFETIME_MS,
   SHARE_ROOT_PREFIX,
   SHARE_ROOT_REQUEST_MARGIN_MS,
+  ShareGrant,
   ShareRoot,
   ShareRootError,
   assertNonExtractableShareKey,
   createPolicyOwnerModeProbe,
   decodeOwnerRootCacao,
   defaultPolicyOwnerModeProbe,
+  ensureShareNetwork,
   ensureShareRoot,
   ownerRootCacaoCid,
   readPolicyOwnerAuthorityMode,
+  shareNetworkIdFor,
   signShareKeyDelegation
 };
 //# sourceMappingURL=share-root.js.map