@tinycloud/share-sdk 1.4.1-beta.0 → 1.4.1-beta.2

package/dist/index.cjs

@@ -5363,6 +5363,23 @@ var unifiedEncryptionNetworkSchema = external_exports.string().refine((value) =>
   const network = separator < 0 ? "" : rest.slice(separator + 1);
   return owner.startsWith("did:") && owner.length > 4 && network.length > 0 && !/[:/%?#\s]/.test(network);
 }, { message: "expected canonical TinyCloud encryption network" });
+var unifiedEncryptionResourceSchema = external_exports.string().refine((value) => {
+  const prefix = "urn:tinycloud:encryption:";
+  if (!value.startsWith(prefix)) return false;
+  const match = /^(did:.+):([^/:?#\s]+)(?:\/(.+))?$/.exec(value.slice(prefix.length));
+  if (match === null) return false;
+  const path = match[3];
+  return path === void 0 || path.split("/").every(
+    (segment) => segment.length > 0 && segment !== "." && segment !== ".." && !/[\\:%?#\s]/.test(segment)
+  );
+}, { message: "expected a canonical TinyCloud encryption resource" });
+var unifiedEncryptionKeyPathSchema = external_exports.string().regex(/^share\/[^/]+$/).refine(
+  (value) => {
+    const segment = value.slice("share/".length);
+    return segment !== "." && segment !== ".." && !/[\\:%?#\s]/.test(segment);
+  },
+  { message: "expected an exact share key path" }
+);
 var unifiedKvCapabilitySchema = external_exports.object({
   kind: external_exports.literal("kv"),
   resource: unifiedResourceSchema,
@@ -5376,7 +5393,7 @@ var unifiedKvCapabilitySchema = external_exports.object({
 }).strict();
 var unifiedEncryptionCapabilitySchema = external_exports.object({
   kind: external_exports.literal("encryption"),
-  resource: unifiedEncryptionNetworkSchema,
+  resource: unifiedEncryptionResourceSchema,
   action: external_exports.literal("tinycloud.encryption/decrypt")
 }).strict();
 var unifiedCapabilitySchema = external_exports.union([unifiedKvCapabilitySchema, unifiedEncryptionCapabilitySchema]);
@@ -5385,6 +5402,7 @@ var unifiedContentSourceSchema = external_exports.object({
   kvResource: unifiedResourceSchema,
   selector: external_exports.union([external_exports.literal("exact"), external_exports.literal("prefix")]),
   encryptionNetwork: unifiedEncryptionNetworkSchema,
+  encryptionKeyPath: unifiedEncryptionKeyPathSchema.optional(),
   encryptedSymmetricKeyDigestHex: external_exports.string().regex(/^[0-9a-f]{64}$/),
   keyVersion: external_exports.number().int().positive(),
   mode: external_exports.union([external_exports.literal("mutable"), external_exports.literal("immutable")]),
@@ -5502,16 +5520,21 @@ function validateV3Invariants(value, ctx) {
   if (value.attestedEnforcerBinding.nodeAudience !== value.target.nodeAudience || value.attestedEnforcerBinding.signature.signerDid !== value.attestedEnforcerBinding.nodeAudience || Date.parse(value.attestedEnforcerBinding.expiresAt) < Date.parse(value.expiry)) {
     ctx.addIssue({ code: external_exports.ZodIssueCode.custom, path: ["attestedEnforcerBinding"], message: "enforcer binding does not cover the target and share lifetime" });
   }
-  if (value.policy.contentSource.shareId !== value.contentSource.shareId || value.policy.contentSource.kvResource !== value.contentSource.kvResource || value.policy.contentSource.selector !== value.contentSource.selector || value.policy.contentSource.encryptionNetwork !== value.encryptionNetwork || value.policy.contentSource.encryptedSymmetricKeyDigestHex !== value.contentSource.encryptedSymmetricKeyDigestHex || value.policy.contentSource.keyVersion !== value.contentSource.keyVersion || value.policy.contentSource.mode !== value.contentSource.mode || value.policy.contentSource.initialCiphertextDigestHex !== value.contentSource.initialCiphertextDigestHex) {
+  const encryptionKeyPath = value.contentSource.encryptionKeyPath;
+  if (encryptionKeyPath !== void 0 && encryptionKeyPath !== `share/${value.contentSource.shareId}`) {
+    ctx.addIssue({ code: external_exports.ZodIssueCode.custom, path: ["contentSource", "encryptionKeyPath"], message: "share key path must name this share" });
+  }
+  if (value.policy.contentSource.shareId !== value.contentSource.shareId || value.policy.contentSource.kvResource !== value.contentSource.kvResource || value.policy.contentSource.selector !== value.contentSource.selector || value.policy.contentSource.encryptionNetwork !== value.encryptionNetwork || value.policy.contentSource.encryptionKeyPath !== encryptionKeyPath || value.policy.contentSource.encryptedSymmetricKeyDigestHex !== value.contentSource.encryptedSymmetricKeyDigestHex || value.policy.contentSource.keyVersion !== value.contentSource.keyVersion || value.policy.contentSource.mode !== value.contentSource.mode || value.policy.contentSource.initialCiphertextDigestHex !== value.contentSource.initialCiphertextDigestHex) {
     ctx.addIssue({ code: external_exports.ZodIssueCode.custom, path: ["contentSource"], message: "content source is not bound to policy" });
   }
   if (value.policy.signature.suite !== "Ed25519" || value.policy.signature.signerDid !== value.policy.ownerDid) {
     ctx.addIssue({ code: external_exports.ZodIssueCode.custom, path: ["policy", "signature"], message: "policy must be signed by its owner" });
   }
   const kvCapabilities = value.policy.capabilityCeiling.filter((capability) => capability.kind === "kv");
-  const decryptCapabilities = value.policy.capabilityCeiling.filter((capability) => capability.kind === "encryption" && capability.resource === value.encryptionNetwork && capability.action === "tinycloud.encryption/decrypt");
+  const expectedEncryptionResource = encryptionKeyPath === void 0 ? value.encryptionNetwork : `${value.encryptionNetwork}/${encryptionKeyPath}`;
+  const decryptCapabilities = value.policy.capabilityCeiling.filter((capability) => capability.kind === "encryption" && capability.resource === expectedEncryptionResource && capability.action === "tinycloud.encryption/decrypt");
   if (value.policy.capabilityCeiling.length !== 2 || kvCapabilities.length !== 1 || decryptCapabilities.length !== 1 || kvCapabilities[0]?.resource !== value.contentSource.kvResource || kvCapabilities[0]?.selector !== value.contentSource.selector) {
-    ctx.addIssue({ code: external_exports.ZodIssueCode.custom, path: ["policy", "capabilityCeiling"], message: "policy ceiling must contain exact decrypt network" });
+    ctx.addIssue({ code: external_exports.ZodIssueCode.custom, path: ["policy", "capabilityCeiling"], message: "policy ceiling must contain the exact decrypt resource" });
   }
 }
 var unsignedShareEnvelopeV3Schema = unsignedShareEnvelopeV3BaseSchema.superRefine(validateV3Invariants);
@@ -5699,6 +5722,7 @@ var SEALED_BLOB_VERSION = 1;
 var AAD = utf8Bytes(ENVELOPE_AAD_LABEL);
 var KEY_LENGTH = 32;
 var NONCE_LENGTH = 12;
+var TAG_LENGTH = 16;
 var HEADER_LENGTH = 1;
 function assertKey(key32) {
   if (key32.length !== KEY_LENGTH) {
@@ -5726,6 +5750,17 @@ async function seal(plaintextBytes, key32) {
   blob.set(ciphertext, HEADER_LENGTH + nonce.length);
   return { blob, cid: await computeCid(blob) };
 }
+async function open(blob, key32) {
+  if (blob.length < HEADER_LENGTH + NONCE_LENGTH + TAG_LENGTH) {
+    throw new TypeError(`sealed blob too short: ${blob.length} bytes`);
+  }
+  if (blob[0] !== SEALED_BLOB_VERSION) {
+    throw new TypeError(`unknown sealed blob version: ${blob[0]}`);
+  }
+  const nonce = blob.subarray(HEADER_LENGTH, HEADER_LENGTH + NONCE_LENGTH);
+  const ciphertext = blob.subarray(HEADER_LENGTH + NONCE_LENGTH);
+  return decryptEnvelope(nonce, ciphertext, key32);
+}
 async function encryptEnvelope(plaintextBytes, key32) {
   const key = await importAesKey(key32, "encrypt");
   const nonce = globalThis.crypto.getRandomValues(new Uint8Array(NONCE_LENGTH));
@@ -5738,6 +5773,19 @@ async function encryptEnvelope(plaintextBytes, key32) {
   );
   return { nonce, ciphertext };
 }
+async function decryptEnvelope(nonce, ciphertext, key32) {
+  if (nonce.length !== NONCE_LENGTH) {
+    throw new TypeError(`nonce must be ${NONCE_LENGTH} bytes, got ${nonce.length}`);
+  }
+  const key = await importAesKey(key32, "decrypt");
+  return new Uint8Array(
+    await globalThis.crypto.subtle.decrypt(
+      { name: "AES-GCM", iv: nonce, additionalData: AAD },
+      key,
+      ciphertext
+    )
+  );
+}
 function isPlainRecord(value) {
   const proto = Object.getPrototypeOf(value);
   return proto === Object.prototype || proto === null;
@@ -5883,6 +5931,7 @@ function equal(left, right) {
   return left.length === right.length && left.every((byte, index) => byte === right[index]);
 }
 var ED25519_VERIFY_OPTS2 = { zip215: false };
+var ENVELOPE_V2_SIGNATURE_DOMAIN = "xyz.tinycloud.share/envelope/v2\0";
 var ENVELOPE_V3_SIGNATURE_DOMAIN = "xyz.tinycloud.share/envelope/v3\0";
 var POLICY_V1_SIGNATURE_DOMAIN = "xyz.tinycloud.policy/policy/v1\0";
 var POLICY_V2_SIGNATURE_DOMAIN = "xyz.tinycloud.policy/policy/v2\0";
@@ -5890,6 +5939,14 @@ var CONTENT_SOURCE_V1_DOMAIN = "xyz.tinycloud.policy/ContentSource/v1\0";
 var POLICY_CAPABILITY_V1_DOMAIN = "xyz.tinycloud.policy/PolicyCapability/v1\0";
 var NATIVE_PROJECTION_V1_DOMAIN = "xyz.tinycloud.policy/NativeProjection/v1\0";
 var ATTESTED_ENFORCER_V2_DOMAIN = "xyz.tinycloud.policy/AttestedEnforcerBinding/v2\0";
+function signingBytesV2(unsigned) {
+  const domain = utf8Bytes(ENVELOPE_V2_SIGNATURE_DOMAIN);
+  const body = utf8Bytes(canonicalize(unsigned));
+  const bytes3 = new Uint8Array(domain.length + body.length);
+  bytes3.set(domain);
+  bytes3.set(body, domain.length);
+  return bytes3;
+}
 function signingBytesV3(unsigned) {
   const domain = utf8Bytes(ENVELOPE_V3_SIGNATURE_DOMAIN);
   const body = utf8Bytes(canonicalize(unsigned));
@@ -5898,6 +5955,17 @@ function signingBytesV3(unsigned) {
   bytes3.set(body, domain.length);
   return bytes3;
 }
+function verifyEnvelopeV2SignatureOnly(envelope) {
+  const parsed = shareEnvelopeV2Schema.parse(envelope);
+  const { signature, ...unsigned } = parsed;
+  return import_ed255193.ed25519.verify(fromBase64Url(signature.value), signingBytesV2(unsigned), ed25519PublicKeyFromDidKey(signature.signerDid), ED25519_VERIFY_OPTS2);
+}
+async function verifyEnvelopeV2(envelope, options) {
+  const parsed = shareEnvelopeV2Schema.parse(envelope);
+  if (parsed.signature.signerDid !== options.expectedSignerDid || !verifyEnvelopeV2SignatureOnly(parsed)) return false;
+  if (parsed.authorizationTarget.kind === "policy") return await computeCid(fromBase64Url(parsed.authorizationTarget.policyBytes)) === parsed.authorizationTarget.policyCid;
+  return true;
+}
 function verifyEnvelopeV3SignatureOnly(envelope) {
   const parsed = shareEnvelopeV3Schema.parse(envelope);
   const { signature, ...unsigned } = parsed;
@@ -5984,6 +6052,52 @@ function base32Lower(bytes3) {
   if (bits > 0) output += alphabet[buffer << 5 - bits & 31];
   return output;
 }
+var KEY_LENGTH2 = 32;
+function assertCanonicalCid(cidString) {
+  const cid2 = CID.parse(cidString);
+  if (cid2.version !== 1 || cid2.code !== code || cid2.multihash.code !== 18 || // sha2-256 (0x12) only, at the link layer too
+  cid2.toString() !== cidString) {
+    throw new TypeError(`not a canonical CIDv1 raw sha2-256 base32 CID: ${cidString}`);
+  }
+}
+function parseShareUrl(url, options = {}) {
+  const parsed = new URL(url);
+  if (parsed.protocol !== "https:") {
+    throw new TypeError(`share URL must be https, got ${parsed.protocol}`);
+  }
+  if (parsed.username !== "" || parsed.password !== "") {
+    throw new TypeError("share URL must not carry userinfo");
+  }
+  if (parsed.search !== "") {
+    throw new TypeError("share URL must not have a query string");
+  }
+  if (options.expectedOrigin !== void 0) {
+    if (!isCanonicalHttpsOrigin(options.expectedOrigin)) {
+      throw new TypeError(
+        `expectedOrigin must be a canonical https origin, got ${options.expectedOrigin}`
+      );
+    }
+    if (parsed.origin !== options.expectedOrigin) {
+      throw new TypeError(
+        `share URL origin ${parsed.origin} does not match expected ${options.expectedOrigin}`
+      );
+    }
+  }
+  const match = /^\/s\/([a-z2-7]+)$/.exec(parsed.pathname);
+  if (!match || match[1] === void 0) {
+    throw new TypeError(`not a share URL path: ${parsed.pathname}`);
+  }
+  const ciphertextCid = match[1];
+  assertCanonicalCid(ciphertextCid);
+  if (!parsed.hash.startsWith("#k=")) {
+    throw new TypeError("share URL is missing the #k= key fragment");
+  }
+  const key32 = fromBase64Url(parsed.hash.slice("#k=".length));
+  if (key32.length !== KEY_LENGTH2) {
+    throw new TypeError(`fragment key must be ${KEY_LENGTH2} bytes, got ${key32.length}`);
+  }
+  return { ciphertextCid, key32 };
+}
 
 // src/artifact-core.ts
 var ARTIFACT_ROOT = "artifacts";
@@ -6085,7 +6199,7 @@ function toShareErrorInfo(error) {
   return { protocol: "tinycloud-share", version: SHARE_RESULT_VERSION, error: { code: "fetch-failed" } };
 }
 function metadataFor(envelope, origin) {
-  const kind = envelope.recipientMatcher.kind === "recipientDid" ? "recipientDid" : envelope.recipientMatcher.kind === "exactEmail" ? "email" : "emailDomain";
+  const kind = envelope.recipientMatcher.kind === "recipientDid" ? "recipientDid" : envelope.recipientMatcher.kind === "exactEmail" ? "email" : envelope.recipientMatcher.kind === "emailDomain" ? "emailDomain" : "bearer";
   return {
     protocol: "tinycloud-share",
     version: 1,
@@ -6100,7 +6214,7 @@ function metadataFor(envelope, origin) {
       ...envelope.display.filename === void 0 ? {} : { filename: envelope.display.filename },
       ...envelope.display.mode === void 0 ? {} : { mode: envelope.display.mode }
     },
-    ...envelope.artifactPin === void 0 ? {} : { artifact: { id: envelope.artifactPin.artifactId, version: envelope.artifactPin.version } }
+    ...envelope.version === 3 && envelope.artifactPin !== void 0 ? { artifact: { id: envelope.artifactPin.artifactId, version: envelope.artifactPin.version } } : {}
   };
 }
 function receiveErrorFor(error) {
@@ -6198,14 +6312,165 @@ async function resolvePolicyShare(link, options) {
   options.onResolvedAddressedEnvelope?.(envelope, cid2);
   return { envelope, origin: url.origin, cid: cid2 };
 }
+async function resolveLegacyV2(link, options) {
+  let parsed;
+  try {
+    parsed = parseShareUrl(link, { ...options.expectedOrigin === void 0 ? {} : { expectedOrigin: options.expectedOrigin } });
+  } catch {
+    throw new ShareReceiveError("invalid-link", "legacy share link format is invalid");
+  }
+  try {
+    options.signal?.throwIfAborted();
+    const origin = new URL(link).origin;
+    const limit = options.maxSealedBlobBytes ?? DEFAULT_MAX_SEALED_BLOB_BYTES;
+    if (!Number.isSafeInteger(limit) || limit <= 0) throw new ShareReceiveError("max-bytes-exceeded", "sealed envelope limit is invalid");
+    let sealed;
+    if (options.fetchBlob !== void 0) {
+      try {
+        sealed = await options.fetchBlob({ origin, cid: parsed.ciphertextCid, ...options.signal === void 0 ? {} : { signal: options.signal } });
+      } catch {
+        throw new ShareReceiveError("fetch-failed", "legacy registry unavailable");
+      }
+    } else {
+      if (options.registryBaseUrl === void 0) throw new ShareReceiveError("fetch-failed", "legacy registry is required");
+      const response = await (options.fetch ?? globalThis.fetch)(`${options.registryBaseUrl.replace(/\/+$/, "")}/ipfs/${parsed.ciphertextCid}?format=raw`, {
+        headers: { accept: "application/vnd.ipld.raw" },
+        redirect: "error",
+        ...options.signal === void 0 ? {} : { signal: options.signal }
+      });
+      if (!response.ok) throw new ShareReceiveError("fetch-failed", "legacy registry unavailable");
+      if (Number(response.headers.get("content-length")) > limit) throw new ShareReceiveError("max-bytes-exceeded", "sealed envelope exceeds the size limit");
+      const reader = response.body?.getReader();
+      if (reader === void 0) throw new ShareReceiveError("fetch-failed", "legacy registry returned no body");
+      const chunks = [];
+      let length3 = 0;
+      for (; ; ) {
+        const part = await reader.read();
+        if (part.done) break;
+        length3 += part.value.length;
+        if (length3 > limit) {
+          await reader.cancel();
+          throw new ShareReceiveError("max-bytes-exceeded", "sealed envelope exceeds the size limit");
+        }
+        chunks.push(part.value);
+      }
+      sealed = new Uint8Array(length3);
+      let offset = 0;
+      for (const chunk of chunks) {
+        sealed.set(chunk, offset);
+        offset += chunk.length;
+      }
+    }
+    options.signal?.throwIfAborted();
+    if (!(sealed instanceof Uint8Array) || sealed.length > limit) throw new ShareReceiveError("max-bytes-exceeded", "sealed envelope exceeds the size limit");
+    if (await computeCid(sealed) !== parsed.ciphertextCid) throw new ShareReceiveError("cid-mismatch", "legacy envelope CID does not match");
+    let plaintext;
+    try {
+      plaintext = await open(sealed, parsed.key32);
+    } catch {
+      throw new ShareReceiveError("decrypt-failed", "legacy envelope could not be opened");
+    }
+    let envelope;
+    try {
+      const encoded = new TextDecoder("utf-8", { fatal: true }).decode(plaintext);
+      const value = JSON.parse(encoded);
+      if (canonicalize(value) !== encoded) throw new Error("non-canonical envelope");
+      envelope = shareEnvelopeV2Schema.parse(value);
+    } catch {
+      throw new ShareReceiveError("envelope-invalid", "legacy envelope is invalid");
+    }
+    return { envelope, origin, cid: parsed.ciphertextCid };
+  } finally {
+    parsed.key32.fill(0);
+  }
+}
+function evidenceMatchesV2(envelope, evidence) {
+  const actions = new Set(evidence.actions.map((action) => action === "read" ? "tinycloud.kv/get" : action === "list" ? "tinycloud.kv/list" : action === "edit" ? "tinycloud.kv/put" : action));
+  const resourceCovers = evidence.resource.kind === "exact" ? envelope.resource.kind === "exact" && evidence.resource.path === envelope.resource.path : envelope.resource.path === evidence.resource.path || envelope.resource.path.startsWith(evidence.resource.path.endsWith("/") ? evidence.resource.path : `${evidence.resource.path}/`);
+  return envelope.authorizationTarget.kind === "policy" && evidence.policyCid === envelope.authorizationTarget.policyCid && evidence.signerDid === envelope.signature.signerDid && evidence.registrationCid.length > 0 && evidence.shareId === envelope.shareId && canonicalize(evidence.recipientMatcher) === canonicalize(envelope.recipientMatcher) && canonicalize(evidence.target) === canonicalize(envelope.target) && resourceCovers && envelope.actions.every((action) => actions.has(action === "read" ? "tinycloud.kv/get" : action === "list" ? "tinycloud.kv/list" : "tinycloud.kv/put")) && canonicalize(evidence.contentSource) === canonicalize(envelope.contentSource) && evidence.contentSourceDigest === envelope.contentSourceDigest && evidence.delegationCid === envelope.delegationCid && evidence.authorityMaterialHandle === envelope.authorityMaterialHandle && evidence.authorityMaterialDigest === envelope.authorityMaterialDigest && evidence.expiresAt === envelope.expiry && Number.isFinite(Date.parse(evidence.expiresAt)) && Date.parse(evidence.expiresAt) === Date.parse(envelope.expiry);
+}
+async function verifyLegacyV2(envelope, options) {
+  try {
+    if (!await verifyEnvelopeV2(envelope, { expectedSignerDid: envelope.signature.signerDid })) throw new Error("signature");
+  } catch {
+    throw new ShareReceiveError("signature-invalid", "legacy envelope signature is invalid");
+  }
+  const expiry = Date.parse(envelope.expiry);
+  if (!Number.isFinite(expiry)) throw new ShareReceiveError("envelope-invalid", "legacy share expiry is invalid");
+  if (expiry <= (options.now?.() ?? Date.now())) throw new ShareReceiveError("expired", "legacy share has expired", { expiresAt: envelope.expiry });
+  if (envelope.authorizationTarget.kind === "policy") {
+    if (options.trustedPolicyAuthority === void 0) throw new ShareReceiveError("envelope-invalid", "a legacy policy authority is required");
+    let evidence;
+    try {
+      evidence = await options.trustedPolicyAuthority.resolve({ policyCid: envelope.authorizationTarget.policyCid, envelope });
+    } catch {
+    }
+    if (evidence === void 0 || !evidenceMatchesV2(envelope, evidence)) throw new ShareReceiveError("capability-invalid", "legacy policy evidence does not match");
+    if (options.trustedSignerDid !== void 0 && options.trustedSignerDid !== evidence.signerDid) throw new ShareReceiveError("signature-invalid", "legacy signer is not trusted");
+  } else if (options.trustedSignerDid === void 0 || options.trustedSignerDid !== envelope.signature.signerDid || envelope.authorizationTarget.kind === "recipientDid" && envelope.recipientMatcher.kind === "recipientDid" && envelope.authorizationTarget.did !== envelope.recipientMatcher.value) {
+    throw new ShareReceiveError("capability-invalid", "legacy recipient authority does not match");
+  }
+}
 async function inspectShare(link, options = {}) {
+  if (isLegacyV2Link(link)) {
+    const legacy = await resolveLegacyV2(link, options);
+    await verifyLegacyV2(legacy.envelope, options);
+    options.onResolvedAddressedEnvelope?.(legacy.envelope, legacy.cid);
+    return { metadata: metadataFor(legacy.envelope, legacy.origin), link: { origin: legacy.origin, cid: legacy.cid, kind: "compact" } };
+  }
   const resolved = await resolvePolicyShare(link, options);
   return { metadata: metadataFor(resolved.envelope, resolved.origin), link: { origin: resolved.origin, cid: resolved.cid, kind: "policy" } };
 }
 async function receiveShare(link, options = {}) {
+  if (isLegacyV2Link(link)) return receiveLegacyV2(link, options);
   const resolved = await resolvePolicyShare(link, options);
   return { state: "authorization-required", method: resolved.envelope.recipientMatcher.kind === "recipientDid" ? "openkey-device" : "email-claim" };
 }
+function isLegacyV2Link(link) {
+  try {
+    const url = new URL(link);
+    return /^\/s\/bafkrei[a-z2-7]{52}$/.test(url.pathname) && url.hash.startsWith("#k=");
+  } catch {
+    return false;
+  }
+}
+async function receiveLegacyV2(link, options) {
+  const resolved = await resolveLegacyV2(link, options);
+  const { envelope } = resolved;
+  await verifyLegacyV2(envelope, options);
+  options.onResolvedAddressedEnvelope?.(envelope, resolved.cid);
+  const method = envelope.recipientMatcher.kind === "recipientDid" ? "openkey-device" : "email-claim";
+  if (options.authorization === void 0) return { state: "authorization-required", method };
+  const result = options.authorizationResumeToken === void 0 ? await options.authorization.begin({ envelope, method }) : await options.authorization.resume({
+    envelope,
+    method,
+    resumeToken: options.authorizationResumeToken,
+    ...options.authorizationProof === void 0 ? {} : { proof: options.authorizationProof }
+  });
+  if (result.state === "authorization-required") return result;
+  if (result.state === "denied") throw new ShareReceiveError("authorization-denied", "legacy share authorization was denied");
+  if (result.value === null || typeof result.value !== "object" || !(result.value.bytes instanceof Uint8Array) || result.value.proof === void 0 || options.authorization.verifyResult === void 0) {
+    throw new ShareReceiveError("content-integrity-failed", "legacy content lacks a verifiable proof");
+  }
+  const authorized = result.value;
+  try {
+    if (!await options.authorization.verifyResult({ envelope, value: authorized, proof: authorized.proof })) throw new Error("proof");
+  } catch {
+    throw new ShareReceiveError("content-integrity-failed", "legacy content proof is invalid");
+  }
+  const bytes3 = authorized.bytes.slice();
+  if (bytes3.length > (options.maxContentBlobBytes ?? DEFAULT_MAX_CONTENT_BLOB_BYTES)) throw new ShareReceiveError("max-bytes-exceeded", "legacy content exceeds the size limit");
+  const bodyDigest = toBase64Url(new Uint8Array(await crypto.subtle.digest("SHA-256", bytes3)));
+  if (authorized.bodyDigest !== bodyDigest || authorized.contentSourceDigest !== envelope.contentSourceDigest || authorized.binding.shareId !== envelope.shareId || authorized.binding.delegationCid !== envelope.delegationCid || authorized.binding.authorityMaterialHandle !== envelope.authorityMaterialHandle || authorized.binding.authorityMaterialDigest !== envelope.authorityMaterialDigest || authorized.binding.resource.kind !== envelope.resource.kind || authorized.binding.resource.path !== envelope.resource.path || authorized.binding.action !== void 0 && !envelope.actions.some((action) => action === authorized.binding.action || `tinycloud.kv/${action}` === authorized.binding.action) || envelope.metadata.byteLength !== void 0 && envelope.metadata.byteLength !== bytes3.length) {
+    throw new ShareReceiveError("content-integrity-failed", "legacy content binding does not match");
+  }
+  let text;
+  try {
+    text = new TextDecoder("utf-8", { fatal: true }).decode(bytes3);
+  } catch {
+  }
+  return { metadata: metadataFor(envelope, resolved.origin), link: { origin: resolved.origin, cid: resolved.cid, kind: "compact" }, bytes: bytes3, ...text === void 0 ? {} : { text } };
+}
 
 // src/publish.ts
 var SHARE_CONTENT_LIMIT = 100 * 1024 * 1024;
@@ -6740,7 +7005,10 @@ async function publishTargetShare(input) {
     expiresAt,
     expiryWasExplicit: input.expiryWasExplicit ?? input.expiresAt !== void 0,
     origin: input.origin,
-    ...input.notify === void 0 ? {} : { notify: input.notify }
+    ...input.notify === void 0 ? {} : { notify: input.notify },
+    ...input.credentialDescriptor === void 0 ? {} : { credentialDescriptor: input.credentialDescriptor },
+    ...input.issuerDid === void 0 ? {} : { issuerDid: input.issuerDid },
+    ...input.issuerKid === void 0 ? {} : { issuerKid: input.issuerKid }
   });
 }
 
@@ -6828,7 +7096,7 @@ async function createPolicy(options, capabilities) {
 function addressedPlan(options) {
   const capabilities = sortCanonical([
     { kind: "kv", resource: options.contentSource.kvResource, selector: options.resource.kind, actions: [...options.policyActions] },
-    { kind: "encryption", resource: options.contentSource.encryptionNetwork, action: "tinycloud.encryption/decrypt" }
+    { kind: "encryption", resource: options.contentSource.encryptionKeyPath === void 0 ? options.contentSource.encryptionNetwork : `${options.contentSource.encryptionNetwork}/${options.contentSource.encryptionKeyPath}`, action: "tinycloud.encryption/decrypt" }
   ]);
   return {
     expiry: rfc3339Seconds(options.expiresAt),
@@ -7158,6 +7426,7 @@ async function addressedShareBodyUpperBound(input) {
     kvResource: `${input.spaceId}/kv/${path}`,
     selector: input.resource.kind,
     encryptionNetwork: input.encryptionNetwork,
+    ...input.encryptionKeyPath === void 0 ? {} : { encryptionKeyPath: input.encryptionKeyPath },
     encryptedSymmetricKeyDigestHex: "f".repeat(64),
     keyVersion: Number.MAX_SAFE_INTEGER,
     mode: "immutable",
@@ -8543,41 +8812,18 @@ function bytes2(value, label) {
   if (decoded.length !== 64 || toBase64Url(decoded) !== value) throw new Error(`${label} is invalid`);
   return decoded;
 }
-var BASE64_ALPHABET = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
 function toBase64(bytes3) {
-  let out = "";
-  for (let i = 0; i < bytes3.length; i += 3) {
-    const b0 = bytes3[i];
-    const b1 = i + 1 < bytes3.length ? bytes3[i + 1] : 0;
-    const b2 = i + 2 < bytes3.length ? bytes3[i + 2] : 0;
-    out += BASE64_ALPHABET[b0 >> 2 & 63];
-    out += BASE64_ALPHABET[(b0 << 4 | b1 >> 4) & 63];
-    out += i + 1 < bytes3.length ? BASE64_ALPHABET[(b1 << 2 | b2 >> 6) & 63] : "=";
-    out += i + 2 < bytes3.length ? BASE64_ALPHABET[b2 & 63] : "=";
-  }
-  return out;
+  return toBase64Url(bytes3).replace(/-/g, "+").replace(/_/g, "/").padEnd(Math.ceil(bytes3.length / 3) * 4, "=");
 }
 function fromBase64(value, label) {
   if (!/^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/.test(value)) {
     throw new Error(`${label} is invalid`);
   }
-  const padding = value.endsWith("==") ? 2 : value.endsWith("=") ? 1 : 0;
-  const out = new Uint8Array(value.length / 4 * 3 - padding);
-  let outIdx = 0;
-  for (let i = 0; i < value.length; i += 4) {
-    const v0 = BASE64_ALPHABET.indexOf(value[i]);
-    const v1 = BASE64_ALPHABET.indexOf(value[i + 1]);
-    const v2 = value[i + 2] === "=" ? 0 : BASE64_ALPHABET.indexOf(value[i + 2]);
-    const v3 = value[i + 3] === "=" ? 0 : BASE64_ALPHABET.indexOf(value[i + 3]);
-    const b0 = v0 << 2 | v1 >> 4;
-    const b1 = (v1 & 15) << 4 | v2 >> 2;
-    const b2 = (v2 & 3) << 6 | v3;
-    if (outIdx < out.length) out[outIdx++] = b0;
-    if (outIdx < out.length) out[outIdx++] = b1;
-    if (outIdx < out.length) out[outIdx++] = b2;
-  }
-  if (toBase64(out) !== value) throw new Error(`${label} is invalid`);
-  return out;
+  try {
+    return fromBase64Url(value.replace(/=+$/, "").replace(/\+/g, "-").replace(/\//g, "_"));
+  } catch {
+    throw new Error(`${label} is invalid`);
+  }
 }
 async function digestBytes2(value) {
   return toBase64Url(new Uint8Array(await crypto.subtle.digest("SHA-256", value)));
@@ -8694,16 +8940,16 @@ function matchesInitialCiphertextDigest(bytes3, expected) {
 function canonicalHashHex(value) {
   return hex3((0, import_sha2565.sha256)(new TextEncoder().encode(canonicalize(value))));
 }
-async function aesGcmDecrypt(key, blob) {
+async function aesGcmDecrypt(key, blob, aad) {
   if (key.length !== 32 || blob.length < 28) throw new Error("encrypted content is malformed");
   const cryptoKey = await crypto.subtle.importKey("raw", key, "AES-GCM", false, ["decrypt"]);
-  return new Uint8Array(await crypto.subtle.decrypt({ name: "AES-GCM", iv: blob.slice(0, 12) }, cryptoKey, blob.slice(12)));
+  return new Uint8Array(await crypto.subtle.decrypt({ name: "AES-GCM", iv: blob.slice(0, 12), ...aad && { additionalData: aad } }, cryptoKey, blob.slice(12)));
 }
-async function aesGcmEncrypt(key, plaintext) {
+async function aesGcmEncrypt(key, plaintext, aad) {
   if (key.length !== 32) throw new Error("encrypted content key is malformed");
   const nonce = crypto.getRandomValues(new Uint8Array(12));
   const cryptoKey = await crypto.subtle.importKey("raw", key, "AES-GCM", false, ["encrypt"]);
-  const ciphertext = new Uint8Array(await crypto.subtle.encrypt({ name: "AES-GCM", iv: nonce }, cryptoKey, plaintext));
+  const ciphertext = new Uint8Array(await crypto.subtle.encrypt({ name: "AES-GCM", iv: nonce, ...aad && { additionalData: aad } }, cryptoKey, plaintext));
   const output = new Uint8Array(nonce.length + ciphertext.length);
   output.set(nonce);
   output.set(ciphertext, nonce.length);
@@ -8718,8 +8964,9 @@ function parseV3InlineEncryptedEnvelope(bytes3, expected) {
   }
   if (value === null || typeof value !== "object" || Array.isArray(value)) throw new Error("encrypted content envelope is malformed");
   const record = value;
-  const allowed = ["v", "networkId", "alg", "keyVersion", "encryptedSymmetricKey", "encryptedSymmetricKeyHash", "ciphertext", "metadata"];
-  if (Object.keys(record).some((key) => !allowed.includes(key)) || record.v !== 1 || record.networkId !== expected.encryptionNetwork || record.alg !== "x25519-aes256gcm/v1" || record.keyVersion !== expected.contentSource.keyVersion || typeof record.encryptedSymmetricKey !== "string" || typeof record.encryptedSymmetricKeyHash !== "string" || record.encryptedSymmetricKeyHash !== expected.contentSource.encryptedSymmetricKeyDigestHex || record.encryptedSymmetricKeyHash !== canonicalHashHex(record.encryptedSymmetricKey) || typeof record.ciphertext !== "string" || record.metadata !== void 0 && (record.metadata === null || typeof record.metadata !== "object" || Array.isArray(record.metadata) || Object.values(record.metadata).some((entry) => typeof entry !== "string"))) {
+  const allowed = ["v", "networkId", "keyPath", "alg", "keyVersion", "encryptedSymmetricKey", "encryptedSymmetricKeyHash", "ciphertext", "aad", "metadata"];
+  const source = expected.contentSource;
+  if (Object.keys(record).some((key) => !allowed.includes(key)) || record.v !== (source.encryptionKeyPath === void 0 ? 1 : 2) || record.networkId !== source.encryptionNetwork || record.networkId !== expected.encryptionNetwork || record.keyPath !== source.encryptionKeyPath || record.keyPath !== void 0 && record.keyPath !== `share/${expected.shareId}` || record.alg !== "x25519-aes256gcm/v1" || record.keyVersion !== source.keyVersion || typeof record.encryptedSymmetricKey !== "string" || typeof record.encryptedSymmetricKeyHash !== "string" || hex3((0, import_sha2565.sha256)(fromBase64(record.encryptedSymmetricKey, "v3 encrypted symmetric key"))) !== source.encryptedSymmetricKeyDigestHex || record.encryptedSymmetricKeyHash !== canonicalHashHex(record.encryptedSymmetricKey) || typeof record.ciphertext !== "string" || record.aad !== void 0 && typeof record.aad !== "string" || record.metadata !== void 0 && (record.metadata === null || typeof record.metadata !== "object" || Array.isArray(record.metadata) || Object.values(record.metadata).some((entry) => typeof entry !== "string"))) {
     throw new Error("encrypted content envelope binding is invalid");
   }
   return record;
@@ -8840,7 +9087,7 @@ var ShareRecipientClient = class {
     this.session = { sessionId: delegation.sessionCid, expiresAt: new Date(compact.payload.exp * 1e3).toISOString(), actions: envelope.actions, resource: envelope.resource };
     return this.session;
   }
-  /** Decrypt a v3 KV value through a fresh recipient-signed decrypt invocation. */
+  /** Decrypt unscoped v1 or path-bound v2 content, independently checking canonical and registered raw-key digests. */
   async decryptV3Content(bytes3) {
     const envelope = this.options.envelope;
     const signer = this.nativeSigner ?? this.signer;
@@ -8848,18 +9095,22 @@ var ShareRecipientClient = class {
     assertArtifactBinding(artifactBindingView(envelope));
     if (!matchesInitialCiphertextDigest(bytes3, envelope.contentSource.initialCiphertextDigestHex)) throw new Error("v3 owner KV ciphertext digest mismatch");
     const encrypted = parseV3InlineEncryptedEnvelope(bytes3, envelope);
+    const ciphertext = fromBase64(encrypted.ciphertext, "v3 encrypted content");
+    if (ciphertext.length < 28) throw new Error("encrypted content is malformed");
+    const aad = encrypted.aad === void 0 ? void 0 : fromBase64(encrypted.aad, "v3 encrypted content AAD");
     const receiverPrivateKey = crypto.getRandomValues(new Uint8Array(32));
     const receiverPublicKey = toBase64(import_ed255195.x25519.getPublicKey(receiverPrivateKey));
     const receiverPublicKeyHash = canonicalHashHex(receiverPublicKey);
-    const body = { type: "tinycloud.encryption.decrypt/v1", targetNode: this.v3NodeAudience, networkId: encrypted.networkId, alg: encrypted.alg, keyVersion: encrypted.keyVersion, encryptedSymmetricKey: encrypted.encryptedSymmetricKey, encryptedSymmetricKeyHash: encrypted.encryptedSymmetricKeyHash, receiverPublicKey, receiverPublicKeyHash };
+    const body = { type: "tinycloud.encryption.decrypt/v1", targetNode: this.v3NodeAudience, networkId: encrypted.networkId, ...encrypted.keyPath === void 0 ? {} : { keyPath: encrypted.keyPath }, alg: encrypted.alg, keyVersion: encrypted.keyVersion, encryptedSymmetricKey: encrypted.encryptedSymmetricKey, encryptedSymmetricKeyHash: encrypted.encryptedSymmetricKeyHash, receiverPublicKey, receiverPublicKeyHash };
     const bodyHash = hex3((0, import_sha2565.sha256)(new TextEncoder().encode(canonicalize(body))));
     const session = verifyCompactUcanAuthorization(this.v3Authorization, this.session.sessionId);
     const now = Math.floor(Date.now() / 1e3);
+    const decryptResource = encrypted.keyPath === void 0 ? encrypted.networkId : `${encrypted.networkId}/${encrypted.keyPath}`;
     const invocation = await signCompactUcanAuthorization({
       issuerDid: this.options.holderDid,
       audienceDid: this.v3NodeAudience,
-      attenuation: { [encrypted.networkId]: { "tinycloud.encryption/decrypt": [{}] } },
-      facts: [{ type: body.type, targetNode: body.targetNode, networkId: body.networkId, bodyHash, encryptedSymmetricKeyHash: body.encryptedSymmetricKeyHash, receiverPublicKeyHash, alg: body.alg, keyVersion: body.keyVersion }],
+      attenuation: { [decryptResource]: { "tinycloud.encryption/decrypt": [{}] } },
+      facts: [{ type: body.type, targetNode: body.targetNode, networkId: body.networkId, ...encrypted.keyPath === void 0 ? {} : { keyPath: encrypted.keyPath }, bodyHash, encryptedSymmetricKeyHash: body.encryptedSymmetricKeyHash, receiverPublicKeyHash, alg: body.alg, keyVersion: body.keyVersion }],
       proofs: [session.cid],
       notBefore: now,
       expiresAt: Math.min(now + 60, session.payload.exp),
@@ -8883,7 +9134,7 @@ var ShareRecipientClient = class {
       const symmetricKey = await aesGcmDecrypt(shared, wrapped.slice(33));
       shared.fill(0);
       if (symmetricKey.length !== 32) throw new Error("v3 content key is malformed");
-      const plaintext = await aesGcmDecrypt(symmetricKey, fromBase64(encrypted.ciphertext, "v3 encrypted content"));
+      const plaintext = await aesGcmDecrypt(symmetricKey, ciphertext, aad);
       this.v3ContentKey?.fill(0);
       this.v3ContentKey = symmetricKey;
       this.v3ContentEnvelope = encrypted;
@@ -8895,7 +9146,9 @@ var ShareRecipientClient = class {
   /** Re-encrypt edited v3 content with the admitted content key. */
   async encryptV3Content(bytes3, mediaType) {
     if (this.options.envelope.version !== 3 || this.v3ContentKey === void 0 || this.v3ContentEnvelope === void 0) throw new Error("v3 content must be decrypted before it can be saved");
-    return new TextEncoder().encode(canonicalize({ ...this.v3ContentEnvelope, ciphertext: toBase64Url(await aesGcmEncrypt(this.v3ContentKey, bytes3)), metadata: { ...this.v3ContentEnvelope.metadata ?? {}, contentType: mediaType } }));
+    const envelope = this.v3ContentEnvelope;
+    const aad = envelope.aad === void 0 ? void 0 : fromBase64(envelope.aad, "v3 encrypted content AAD");
+    return new TextEncoder().encode(canonicalize({ ...envelope, ciphertext: toBase64(await aesGcmEncrypt(this.v3ContentKey, bytes3, aad)), metadata: { ...envelope.metadata ?? {}, contentType: mediaType } }));
   }
   async resumeWithProof(envelope, resumeToken, proof) {
     void envelope;