@tinycloud/share-sdk 1.0.0-beta.6 → 1.0.0-beta.8

package/dist/index.cjs

@@ -41,9 +41,11 @@ __export(index_exports, {
   SharePublishError: () => SharePublishError,
   ShareReceiveError: () => ShareReceiveError,
   ShareRecipientClient: () => ShareRecipientClient,
+  addressedCredentialRequirement: () => addressedCredentialRequirement,
   authorizationMethodForTarget: () => authorizationMethodForTarget,
   authorizeShare: () => authorizeShare,
   canonicalOwnerSharePolicy: () => canonicalOwnerSharePolicy,
+  canonicalShareFilename: () => canonicalShareFilename,
   canonicalize: () => canonicalize,
   checkBearerDelegation: () => checkBearerDelegation,
   claimShare: () => claimShare,
@@ -55,6 +57,7 @@ __export(index_exports, {
   createShareV2HolderBindingArtifact: () => createShareV2HolderBindingArtifact,
   deliverCredentialInvitation: () => deliverCredentialInvitation,
   fromBase64Url: () => fromBase64Url,
+  hasUnsafeFilenameCodePoint: () => hasUnsafeFilenameCodePoint,
   historyRecordForPublishedShare: () => historyRecordForPublishedShare,
   inspectShare: () => inspectShare,
   listShares: () => listShares,
@@ -63,6 +66,7 @@ __export(index_exports, {
   openNativeShare: () => openNativeShare,
   parseAddressedEnvelope: () => parseAddressedEnvelope,
   parseNativeShareUrl: () => parseNativeShareUrl,
+  prepareAddressedShare: () => prepareAddressedShare,
   publishAddressedShare: () => publishAddressedShare,
   publishPolicyShare: () => publishPolicyShare,
   publishTargetShare: () => publishTargetShare,
@@ -83,6 +87,19 @@ __export(index_exports, {
 });
 module.exports = __toCommonJS(index_exports);
 
+// src/filename-policy.ts
+var UNSAFE_FILENAME_CODE_POINT = /[\p{Cc}\p{Cf}\p{Cs}\u2028\u2029]/u;
+function hasUnsafeFilenameCodePoint(value) {
+  return UNSAFE_FILENAME_CODE_POINT.test(value);
+}
+function canonicalShareFilename(value) {
+  const canonical = value.normalize("NFC");
+  if (canonical.length === 0 || canonical === "." || canonical === ".." || canonical.includes("/") || canonical.includes("\\") || hasUnsafeFilenameCodePoint(canonical)) {
+    throw new TypeError("share filename is unsafe");
+  }
+  return canonical;
+}
+
 // ../share-envelope/dist/index.js
 var import_sha2 = require("@noble/hashes/sha2");
 var import_ed25519 = require("@noble/curves/ed25519");
@@ -5764,6 +5781,21 @@ function serialize(value) {
 function canonicalize(value) {
   return serialize(value);
 }
+var LABEL = /^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$/;
+function isCanonicalEmailDomain(value) {
+  if (value.length === 0 || value.length > 253) return false;
+  const labels = value.split(".");
+  return labels.length >= 2 && labels.every((label) => LABEL.test(label)) && !/^[0-9]+$/.test(labels.at(-1));
+}
+function canonicalMailbox(value) {
+  const email = value.trim().toLowerCase();
+  const at = email.indexOf("@");
+  if (at <= 0 || at !== email.lastIndexOf("@")) return void 0;
+  const local = email.slice(0, at);
+  const domain = email.slice(at + 1);
+  if (local.length > 64 || !/^[a-z0-9#$&'*+/=?^_`{|}~-]+(?:\.[a-z0-9#$&'*+/=?^_`{|}~-]+)*$/.test(local) || !isCanonicalEmailDomain(domain)) return void 0;
+  return Object.freeze({ email, domain });
+}
 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");
@@ -6509,12 +6541,6 @@ var base58flickr2 = baseX2({
 });
 
 // src/targets.ts
-function validEmail(value) {
-  return /^[^@\s]+@[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?(?:\.[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?)*$/i.test(value);
-}
-function validDomain(value) {
-  return /^(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?)(?:\.(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?))+$/i.test(value);
-}
 function validRecipientDid(value) {
   if (value.length === 0 || value.length > 2048 || /[\u0000-\u0020\u007f]/.test(value)) return false;
   const parts = value.split(":");
@@ -6544,18 +6570,28 @@ function normalizeShareTarget(target) {
     return { kind: target.kind, did: target.did };
   }
   if (target.kind === "email") {
-    if (!validEmail(target.address)) throw new TypeError("recipient email is invalid");
-    const at = target.address.lastIndexOf("@");
-    return { kind: target.kind, address: `${target.address.slice(0, at)}@${target.address.slice(at + 1).toLowerCase()}` };
+    const mailbox = canonicalMailbox(target.address);
+    if (mailbox === void 0) throw new TypeError("recipient email is invalid");
+    return { kind: target.kind, address: mailbox.email };
   }
-  if (!validDomain(target.domain)) throw new TypeError("recipient email domain is invalid");
-  return { kind: target.kind, domain: target.domain.toLowerCase() };
+  const domain = target.domain.toLowerCase();
+  if (!isCanonicalEmailDomain(domain)) throw new TypeError("recipient email domain is invalid");
+  return { kind: target.kind, domain };
 }
 function targetAuthorizationMethod(target) {
   return authorizationMethodForTarget(target);
 }
+function publishFilename(value) {
+  try {
+    return canonicalShareFilename(value);
+  } catch {
+    throw new SharePublishError("invalid-argument", hasUnsafeFilenameCodePoint(value) ? "filename contains control or invisible characters" : "filename must be one safe path segment");
+  }
+}
 async function publishTargetShare(input) {
   const target = normalizeShareTarget(input.target);
+  const filename = publishFilename(input.filename);
+  const files = input.files?.map((file) => ({ ...file, filename: publishFilename(file.filename) }));
   if (input.targetAdapter === void 0) {
     if (target.kind === "bearer") throw new SharePublishError("authority-required", "native bearer publication requires an authenticated TinyCloud node");
     return {
@@ -6581,9 +6617,6 @@ async function publishTargetShare(input) {
     return bytes3;
   })();
   if (source.byteLength === 0) throw new SharePublishError("invalid-argument", "share content is empty");
-  if (!input.filename || input.filename === "." || input.filename === ".." || /[/\\\u0000-\u001f\u007f]/.test(input.filename)) {
-    throw new SharePublishError("invalid-argument", "filename must be one safe path segment");
-  }
   if (target.kind === "bearer" && input.allowBinary !== true) {
     try {
       new TextDecoder("utf-8", { fatal: true }).decode(source);
@@ -6591,10 +6624,10 @@ async function publishTargetShare(input) {
       throw new SharePublishError("invalid-argument", "Markdown input must be valid UTF-8");
     }
   }
-  const files = input.files === void 0 || input.files.length === 0 ? [{ bytes: source }] : input.files;
+  const publishFiles = files === void 0 || files.length === 0 ? [{ bytes: source }] : files;
   const limit = input.maxBytes ?? SHARE_CONTENT_LIMIT;
   let totalBytes = 0;
-  for (const file of files) {
+  for (const file of publishFiles) {
     totalBytes += file.bytes.byteLength;
     if (!Number.isSafeInteger(totalBytes) || totalBytes > limit) {
       throw new SharePublishError("max-bytes-exceeded", "share publication exceeds the combined byte limit");
@@ -6605,8 +6638,8 @@ async function publishTargetShare(input) {
   if (!Number.isFinite(expiresAt.getTime()) || expiresAt.getTime() <= nowMs) throw new SharePublishError("invalid-argument", "expiresAt must be a valid future time");
   return input.targetAdapter.publish({
     source,
-    filename: input.filename,
-    ...input.files === void 0 ? {} : { files: input.files },
+    filename,
+    ...files === void 0 ? {} : { files },
     ...input.mediaType === void 0 ? {} : { mediaType: input.mediaType },
     ...input.resourceKind === void 0 ? {} : { resourceKind: input.resourceKind },
     ...input.actions === void 0 ? {} : { actions: input.actions },
@@ -6636,9 +6669,7 @@ function targetKind(target) {
 }
 function assertSafeInput(input) {
   if (!/^[A-Za-z0-9_-]{16,128}$/.test(input.shareId)) throw new TypeError("addressed share id is invalid");
-  if (input.filename.length === 0 || input.filename === "." || input.filename === ".." || /[/\\\u0000-\u001f\u007f]/.test(input.filename)) throw new TypeError("addressed filename is invalid");
   if (!Number.isSafeInteger(input.byteLength) || input.byteLength < 0 || input.byteLength > SHARE_CONTENT_LIMIT) throw new TypeError("addressed content length is invalid");
-  if (input.actions.length === 0 || input.policyActions.length === 0) throw new TypeError("addressed share actions are empty");
   if (!Number.isFinite(input.expiresAt.getTime()) || input.expiresAt.getTime() <= Date.now()) throw new TypeError("addressed share expiry must be in the future");
   if (input.artifact === "html" && (input.resource.kind !== "prefix" || !input.actions.includes("read") || !input.actions.includes("list"))) throw new TypeError("html artifacts require a readable prefix");
   if (input.contentSource.shareId !== input.shareId || input.contentSource.selector !== input.resource.kind) throw new TypeError("addressed content source is not bound to the share");
@@ -6731,23 +6762,60 @@ function publicationResult(input) {
   Object.defineProperty(result, "deliveryMaterial", { enumerable: false, value: input.deliveryMaterial });
   return result;
 }
+var EMAIL_PROFILE = { id: "tinycloud.email-proof/v1", version: 1 };
 var EMAIL_DOMAIN_PROFILE = { id: "tinycloud.email-domain-proof/v1", version: 1 };
 var EMAIL_CREDENTIAL_TYPE = { id: "opencredentials.email/v1", version: 1 };
+var EMAIL_DESCRIPTOR_DIGEST = "1tg-qphmKBVtNwzVg9xyz-xxqt_xtMXAsQyXw46m8S0";
 var EMAIL_DOMAIN_DESCRIPTOR_DIGEST = "33X5mAkZZgApdD3xh_T-3KS5moop0J2Nloi2nqWsdWY";
-function assertEmailDomainPolicy(options, domain) {
-  if (!options.actions.every((action) => action === "read" || action === "list") || !options.policyActions.every((action) => action === "tinycloud.kv/get" || action === "tinycloud.kv/list" || action === "tinycloud.kv/metadata")) throw new TypeError("email-domain shares are view-only");
-  if (options.deliveryEmail !== void 0) throw new TypeError("email-domain shares are not emailed");
-  const commitment = options.credentialRequirement;
-  if (commitment === void 0) throw new TypeError("email-domain shares require a credential requirement");
-  if (canonicalize(commitment.profile) !== canonicalize(EMAIL_DOMAIN_PROFILE) || canonicalize(commitment.credentialType) !== canonicalize(EMAIL_CREDENTIAL_TYPE) || commitment.descriptorDigest !== EMAIL_DOMAIN_DESCRIPTOR_DIGEST) throw new TypeError("email-domain shares require the email-domain credential profile");
-  const expected = { type: "TinyCloudCredentialRequirement", version: 1, profile: EMAIL_DOMAIN_PROFILE, credentialType: EMAIL_CREDENTIAL_TYPE, claims: { emailDomain: domain }, maxAgeSeconds: 300 };
-  if (toBase64Url((0, import_sha2562.sha256)(textEncoder.encode(canonicalize(expected)))) !== commitment.requirementDigest) throw new TypeError("credential requirement is not bound to the email domain");
-}
-async function publishAddressedShare(options) {
-  assertSafeInput(options);
-  const target = normalizeShareTarget(options.target);
+var EMAIL_CREDENTIAL_ISSUER_DID = "did:web:issuer.credentials.org";
+var EMAIL_CREDENTIAL_ISSUER_KID = `${EMAIL_CREDENTIAL_ISSUER_DID}#controller`;
+function mailboxCredentialCommitment(target) {
+  const profile = target.kind === "email" ? EMAIL_PROFILE : EMAIL_DOMAIN_PROFILE;
+  const requirement = target.kind === "email" ? { type: "TinyCloudCredentialRequirement", version: 1, profile, credentialType: EMAIL_CREDENTIAL_TYPE, claims: { email: target.address }, maxAgeSeconds: 3600 } : { type: "TinyCloudCredentialRequirement", version: 1, profile, credentialType: EMAIL_CREDENTIAL_TYPE, claims: { emailDomain: target.domain }, maxAgeSeconds: 300 };
+  return {
+    type: "TinyCloudPolicyCredentialRequirement",
+    version: 1,
+    requirementDigest: toBase64Url((0, import_sha2562.sha256)(textEncoder.encode(canonicalize(requirement)))),
+    descriptorDigest: target.kind === "email" ? EMAIL_DESCRIPTOR_DIGEST : EMAIL_DOMAIN_DESCRIPTOR_DIGEST,
+    issuerDid: EMAIL_CREDENTIAL_ISSUER_DID,
+    issuerKid: EMAIL_CREDENTIAL_ISSUER_KID,
+    profile,
+    credentialType: EMAIL_CREDENTIAL_TYPE
+  };
+}
+function addressedCredentialRequirement(target) {
+  const normalized = normalizeShareTarget(target);
+  if (normalized.kind !== "email" && normalized.kind !== "emailDomain") throw new TypeError("a mailbox target is required");
+  return mailboxCredentialCommitment(normalized);
+}
+function prepareAddressedShare(request) {
+  try {
+    canonicalShareFilename(request.filename);
+  } catch {
+    throw new TypeError("addressed filename is invalid");
+  }
+  if (request.actions.length === 0 || request.policyActions.length === 0) throw new TypeError("addressed share actions are empty");
+  const target = normalizeShareTarget(request.target);
   if (target.kind === "bearer") throw new TypeError("addressed target is required");
-  if (target.kind === "emailDomain") assertEmailDomainPolicy(options, target.domain);
+  if (target.kind === "recipientDid") return { target };
+  if (target.kind === "emailDomain") {
+    if (!request.actions.every((action) => action === "read" || action === "list") || !request.policyActions.every((action) => action === "tinycloud.kv/get" || action === "tinycloud.kv/list" || action === "tinycloud.kv/metadata")) throw new TypeError("email-domain shares are view-only");
+    if (request.deliveryEmail !== void 0) throw new TypeError("email-domain shares are not emailed");
+  }
+  return { target, credentialRequirement: mailboxCredentialCommitment(target) };
+}
+function assertMailboxCommitment(commitment, target) {
+  const label = target.kind === "email" ? "email" : "email-domain";
+  if (commitment === void 0) throw new TypeError(`${label} shares require a credential requirement`);
+  const expected = mailboxCredentialCommitment(target);
+  if (canonicalize(commitment.profile) !== canonicalize(expected.profile) || canonicalize(commitment.credentialType) !== canonicalize(expected.credentialType) || commitment.descriptorDigest !== expected.descriptorDigest || commitment.issuerDid !== expected.issuerDid || commitment.issuerKid !== expected.issuerKid) throw new TypeError(`${label} shares require the ${label} credential profile`);
+  if (commitment.requirementDigest !== expected.requirementDigest) throw new TypeError(`credential requirement is not bound to the email ${target.kind === "email" ? "address" : "domain"}`);
+}
+async function publishAddressedShare(input) {
+  assertSafeInput(input);
+  const { target } = prepareAddressedShare(input);
+  const options = { ...input, filename: canonicalShareFilename(input.filename) };
+  if (target.kind !== "recipientDid") assertMailboxCommitment(options.credentialRequirement, target);
   const expiry = rfc3339Seconds(options.expiresAt);
   const matcher = targetMatcher(target);
   const capabilities = sortCanonical([
@@ -7858,17 +7926,20 @@ var ShareNotifyError = class extends Error {
 };
 function recipientMatchesShareRecord(record, recipient) {
   const matcher = record.recipientMatcher;
-  if (matcher.kind === "bearer" || matcher.kind === "recipientDid") return false;
-  if (matcher.kind === "exactEmail") return matcher.value === recipient;
-  const at = recipient.lastIndexOf("@");
-  return at > 0 && recipient.slice(at + 1).toLowerCase() === matcher.value;
+  const mailbox = canonicalMailbox(recipient);
+  if (mailbox === void 0) return false;
+  if (matcher.kind === "exactEmail") return canonicalMailbox(matcher.value)?.email === mailbox.email;
+  if (matcher.kind === "emailDomain") return mailbox.domain === matcher.value;
+  return false;
 }
 async function notifyShare(input) {
-  if (!input.shareId || !input.recipient || !input.recipient.includes("@")) throw new ShareNotifyError("recipient is invalid");
-  if (input.record !== void 0 && !recipientMatchesShareRecord(input.record, input.recipient)) {
+  const mailbox = canonicalMailbox(input.recipient);
+  if (!input.shareId || mailbox === void 0) throw new ShareNotifyError("recipient is invalid");
+  const recipient = mailbox.email;
+  if (input.record !== void 0 && !recipientMatchesShareRecord(input.record, recipient)) {
     throw new ShareNotifyError("recipient does not match the stored share target");
   }
-  const idempotencyKey = input.idempotencyKey ?? await defaultIdempotencyKey(input.shareId, input.recipient);
+  const idempotencyKey = input.idempotencyKey ?? await defaultIdempotencyKey(input.shareId, recipient);
   const attemptsLimit = input.maxAttempts ?? 3;
   if (!Number.isSafeInteger(attemptsLimit) || attemptsLimit < 1 || attemptsLimit > 8) throw new ShareNotifyError("maxAttempts is invalid");
   let attempts = 0;
@@ -7877,7 +7948,7 @@ async function notifyShare(input) {
     if (input.signal?.aborted) throw new ShareNotifyError("share delivery was cancelled");
     attempts += 1;
     try {
-      const state = await input.adapter.deliver({ shareId: input.shareId, recipient: input.recipient, idempotencyKey, ...input.record === void 0 ? {} : { record: input.record }, ...input.signal === void 0 ? {} : { signal: input.signal } });
+      const state = await input.adapter.deliver({ shareId: input.shareId, recipient, idempotencyKey, ...input.record === void 0 ? {} : { record: input.record }, ...input.signal === void 0 ? {} : { signal: input.signal } });
       return { protocol: "tinycloud-share", version: 1, shareId: input.shareId, state, idempotencyKey, attempts };
     } catch (error) {
       lastError = error;
@@ -8606,9 +8677,11 @@ async function openNativeShare(sharing, link) {
   SharePublishError,
   ShareReceiveError,
   ShareRecipientClient,
+  addressedCredentialRequirement,
   authorizationMethodForTarget,
   authorizeShare,
   canonicalOwnerSharePolicy,
+  canonicalShareFilename,
   canonicalize,
   checkBearerDelegation,
   claimShare,
@@ -8620,6 +8693,7 @@ async function openNativeShare(sharing, link) {
   createShareV2HolderBindingArtifact,
   deliverCredentialInvitation,
   fromBase64Url,
+  hasUnsafeFilenameCodePoint,
   historyRecordForPublishedShare,
   inspectShare,
   listShares,
@@ -8628,6 +8702,7 @@ async function openNativeShare(sharing, link) {
   openNativeShare,
   parseAddressedEnvelope,
   parseNativeShareUrl,
+  prepareAddressedShare,
   publishAddressedShare,
   publishPolicyShare,
   publishTargetShare,