@tinycloud/share-sdk 1.0.0-beta.5 → 1.0.0-beta.7

package/dist/index.d.cts

@@ -185,6 +185,7 @@ interface SharePublishOptions {
     readonly allowBinary?: boolean;
     readonly target?: SharePublishTarget;
     readonly expiresAt?: Date;
+    readonly expiryWasExplicit?: boolean;
     readonly origin: string;
     readonly maxBytes?: number;
     readonly now?: () => number;
@@ -205,6 +206,7 @@ interface PublishedShareMetadata {
         readonly path: string;
     };
     readonly actions: readonly string[];
+    readonly expiryClamped?: boolean;
     readonly expiresAt: string;
     readonly display: {
         readonly filename?: string;
@@ -274,6 +276,7 @@ type ShareTarget = SharePublishTarget;
 interface TargetPublishInput {
     readonly source: Uint8Array;
     readonly filename: string;
+    readonly mediaType?: string;
     /** Additional files for a prefix resource; source remains the first file for compatibility. */
     readonly files?: readonly {
         readonly bytes: Uint8Array;
@@ -282,8 +285,8 @@ interface TargetPublishInput {
     }[];
     readonly target: ShareTarget;
     readonly expiresAt: Date;
+    readonly expiryWasExplicit?: boolean;
     readonly origin: string;
-    readonly mediaType?: string;
     readonly resourceKind?: "exact" | "prefix";
     readonly actions?: readonly ("read" | "list" | "edit")[];
     readonly notify?: boolean;
@@ -587,6 +590,29 @@ interface AddressedSharePublishOptions {
     readonly onDeliveryMaterial?: (input: PublishedShareDeliveryMaterial) => void;
     readonly authority: AddressedPublishAuthority;
 }
+type MailboxTarget = Extract<ShareTarget, {
+    readonly kind: "email" | "emailDomain";
+}>;
+/** The Policy/v2 credential commitment a share addressed to `target` must carry. */
+declare function addressedCredentialRequirement(target: MailboxTarget): PolicyCredentialRequirementV1;
+/** Facts every addressed-share check needs, available before any side effect. */
+type AddressedShareRequest = Pick<AddressedSharePublishOptions, "target" | "actions" | "policyActions" | "filename" | "deliveryEmail">;
+interface PreparedAddressedShare {
+    /** The canonical target the envelope's recipient matcher will carry. */
+    readonly target: Exclude<ShareTarget, {
+        readonly kind: "bearer";
+    }>;
+    /** Present for mailbox targets: the Policy/v2 commitment to pass to `publishAddressedShare`. */
+    readonly credentialRequirement?: PolicyCredentialRequirementV1;
+}
+/**
+ * Runs every argument and target check of `publishAddressedShare` that does
+ * not depend on stored content, and derives the credential commitment. It has
+ * no side effects, so senders call it before uploading content or publishing
+ * a location record; a refused share then leaves nothing behind.
+ */
+declare function prepareAddressedShare(request: AddressedShareRequest): PreparedAddressedShare;
+/** Canonical application-neutral Policy/v3 addressed publisher shared by browser and CLI. */
 declare function publishAddressedShare(options: AddressedSharePublishOptions): Promise<PublishedShare>;
 
 interface ShareCacheKey {
@@ -795,7 +821,11 @@ declare class ShareNotifyError extends Error {
     readonly code: "delivery-failed";
     constructor(message?: string);
 }
-/** Match a delivery address against the recipient constraint recorded when the share was created. */
+/**
+ * Match a delivery address against the recipient constraint recorded when the
+ * share was created. Both sides compare in canonical mailbox form, which is
+ * the only form the credential issuer accepts.
+ */
 declare function recipientMatchesShareRecord(record: SenderShareRecord, recipient: string): boolean;
 /**
  * Delivery is deliberately separate from publication. A failed notification
@@ -1058,6 +1088,12 @@ declare function resumeShareAuthorization<T>(input: {
 
 /** Fragment-only adapter for TinyCloud's public SharingService. */
 declare const NATIVE_SHARE_FRAGMENT_PARAMETER = "tc1";
+interface NativeShareResult {
+    readonly url: string;
+    readonly delegationCid: string;
+    readonly expiresAt: Date;
+    readonly spaceId: string;
+}
 interface NativeSharingService {
     generate(params: {
         readonly path: string;
@@ -1078,15 +1114,10 @@ declare function createNativeShare(sharing: NativeSharingService, input: {
     readonly path: string;
     readonly expiresAt: Date;
     readonly viewerOrigin: string;
-}): Promise<{
-    readonly url: string;
-    readonly delegationCid: string;
-    readonly expiresAt: Date;
-    readonly spaceId: string;
-}>;
+}): Promise<NativeShareResult>;
 /** Extract only a single tc1 fragment. Path/query/mixed legacy forms are refused. */
 declare function parseNativeShareUrl(value: string): string;
 /** Receive through the public SDK without creating another transport protocol. */
 declare function openNativeShare(sharing: NativeSharingService, link: string): Promise<unknown>;
 
-export { type AddressedOwnerRootInput, type AddressedOwnerRootReceipt, type AddressedPolicyRegistrationInput, type AddressedPolicyRegistrationReceipt, type AddressedPublishAuthority, type AddressedSharePublishOptions, type CreateOwnerDelegationParams, CredentialInvitationError, type CredentialInvitationErrorCode, type CredentialInvitationReceipt, type CredentialInvitationResult, DEFAULT_MAX_CONTENT_BLOB_BYTES, DEFAULT_MAX_SEALED_BLOB_BYTES, DEFAULT_SHARE_LIFETIME_MS, type DelegatedShareKey, EncryptedSenderShareHistory, type EncryptedShareHistoryStorage, MAX_CONTENT_BYTES, MemoryEncryptedShareHistoryStorage, MemorySenderShareKeyStorage, MemorySenderShareRecordStorage, MemoryShareCache, NATIVE_SHARE_FRAGMENT_PARAMETER, type NativeSharingService, OWNER_SHARE_REGISTRATION_DOMAIN, type OwnerDelegationPermission, type OwnerDelegationReceipt, type OwnerShareAction, type OwnerShareDecryption, type OwnerShareMatcher, type OwnerSharePolicyRegistration, type OwnerSharePolicyRegistrationReceipt, type OwnerSharePolicyV2, type ParsedAddressedEnvelope, type PublishedShare, type PublishedShareDeliveryMaterial, type PublishedShareMetadata, type RegisterOwnerSharePolicyParams, SHARE_CONTENT_LIMIT, SHARE_PUBLISH_RESULT_VERSION, SHARE_RESULT_VERSION, SHARE_V2_PROTOCOL, type SenderShareKeyStorage, type SenderShareRecord, type SenderShareRecordStorage, type SenderShareRevocationScope, SenderShareStore, type ShareAuthorizationAdapter, type ShareAuthorizationDenied, type ShareAuthorizationMethod, type ShareAuthorizationReady, type ShareAuthorizationRequired, type ShareAuthorizationResult, type ShareAuthorizedContent, type ShareCache, type ShareCacheEntry, type ShareCacheKey, type ShareCacheMetadata, type ShareDeliveryAdapter, type ShareErrorCode, type ShareErrorInfo, type ShareFetchOptions, type ShareHistoryView, type ShareInspection, type ShareMetadata, type ShareNodeTrust, ShareNotifyError, type ShareNotifyInput, type ShareNotifyResult, type ShareNotifyState, type SharePolicyChallenge, type SharePolicyPublishAdapter, type SharePolicyRootRevocation, type SharePolicySession, type SharePresentationMaterial, SharePublishError, type SharePublishErrorCode, type SharePublishOptions, type SharePublishTarget, type ShareReceiveAuthorizationRequired, ShareReceiveError, type ShareReceiveOutcome, type ShareReceiveResult, ShareRecipientClient, type ShareRecipientClientOptions, type ShareRevocationAdapter, type ShareRevocationResult, type ShareTarget, type SignedDelegation, type TargetPublishAdapter, type TargetPublishInput, type TargetPublishOutcome, authorizationMethodForTarget, authorizeShare, canonicalOwnerSharePolicy, claimShare, computeOwnerShareRegistrationCid, createAddressedAuthorization, createDelegatedShareKey, createNativeShare, createPolicyEnforcementDelegation, createShareV2HolderBindingArtifact, deliverCredentialInvitation, historyRecordForPublishedShare, inspectShare, listShares, normalizeShareTarget, notifyShare, openNativeShare, parseAddressedEnvelope, parseNativeShareUrl, publishAddressedShare, publishPolicyShare, publishTargetShare, receiveShare, recipientMatchesShareRecord, redactPublishedShare, restoreDelegatedShareKey, resumeShareAuthorization, revokeShare, showShare, targetAuthorizationMethod, toShareErrorInfo, validateOwnerSharePolicyRegistration, validateOwnerSharePolicyRegistrationBytes };
+export { type AddressedOwnerRootInput, type AddressedOwnerRootReceipt, type AddressedPolicyRegistrationInput, type AddressedPolicyRegistrationReceipt, type AddressedPublishAuthority, type AddressedSharePublishOptions, type AddressedShareRequest, type CreateOwnerDelegationParams, CredentialInvitationError, type CredentialInvitationErrorCode, type CredentialInvitationReceipt, type CredentialInvitationResult, DEFAULT_MAX_CONTENT_BLOB_BYTES, DEFAULT_MAX_SEALED_BLOB_BYTES, DEFAULT_SHARE_LIFETIME_MS, type DelegatedShareKey, EncryptedSenderShareHistory, type EncryptedShareHistoryStorage, MAX_CONTENT_BYTES, MemoryEncryptedShareHistoryStorage, MemorySenderShareKeyStorage, MemorySenderShareRecordStorage, MemoryShareCache, NATIVE_SHARE_FRAGMENT_PARAMETER, type NativeShareResult, type NativeSharingService, OWNER_SHARE_REGISTRATION_DOMAIN, type OwnerDelegationPermission, type OwnerDelegationReceipt, type OwnerShareAction, type OwnerShareDecryption, type OwnerShareMatcher, type OwnerSharePolicyRegistration, type OwnerSharePolicyRegistrationReceipt, type OwnerSharePolicyV2, type ParsedAddressedEnvelope, type PreparedAddressedShare, type PublishedShare, type PublishedShareDeliveryMaterial, type PublishedShareMetadata, type RegisterOwnerSharePolicyParams, SHARE_CONTENT_LIMIT, SHARE_PUBLISH_RESULT_VERSION, SHARE_RESULT_VERSION, SHARE_V2_PROTOCOL, type SenderShareKeyStorage, type SenderShareRecord, type SenderShareRecordStorage, type SenderShareRevocationScope, SenderShareStore, type ShareAuthorizationAdapter, type ShareAuthorizationDenied, type ShareAuthorizationMethod, type ShareAuthorizationReady, type ShareAuthorizationRequired, type ShareAuthorizationResult, type ShareAuthorizedContent, type ShareCache, type ShareCacheEntry, type ShareCacheKey, type ShareCacheMetadata, type ShareDeliveryAdapter, type ShareErrorCode, type ShareErrorInfo, type ShareFetchOptions, type ShareHistoryView, type ShareInspection, type ShareMetadata, type ShareNodeTrust, ShareNotifyError, type ShareNotifyInput, type ShareNotifyResult, type ShareNotifyState, type SharePolicyChallenge, type SharePolicyPublishAdapter, type SharePolicyRootRevocation, type SharePolicySession, type SharePresentationMaterial, SharePublishError, type SharePublishErrorCode, type SharePublishOptions, type SharePublishTarget, type ShareReceiveAuthorizationRequired, ShareReceiveError, type ShareReceiveOutcome, type ShareReceiveResult, ShareRecipientClient, type ShareRecipientClientOptions, type ShareRevocationAdapter, type ShareRevocationResult, type ShareTarget, type SignedDelegation, type TargetPublishAdapter, type TargetPublishInput, type TargetPublishOutcome, addressedCredentialRequirement, authorizationMethodForTarget, authorizeShare, canonicalOwnerSharePolicy, claimShare, computeOwnerShareRegistrationCid, createAddressedAuthorization, createDelegatedShareKey, createNativeShare, createPolicyEnforcementDelegation, createShareV2HolderBindingArtifact, deliverCredentialInvitation, historyRecordForPublishedShare, inspectShare, listShares, normalizeShareTarget, notifyShare, openNativeShare, parseAddressedEnvelope, parseNativeShareUrl, prepareAddressedShare, publishAddressedShare, publishPolicyShare, publishTargetShare, receiveShare, recipientMatchesShareRecord, redactPublishedShare, restoreDelegatedShareKey, resumeShareAuthorization, revokeShare, showShare, targetAuthorizationMethod, toShareErrorInfo, validateOwnerSharePolicyRegistration, validateOwnerSharePolicyRegistrationBytes };

package/dist/index.d.ts

@@ -185,6 +185,7 @@ interface SharePublishOptions {
     readonly allowBinary?: boolean;
     readonly target?: SharePublishTarget;
     readonly expiresAt?: Date;
+    readonly expiryWasExplicit?: boolean;
     readonly origin: string;
     readonly maxBytes?: number;
     readonly now?: () => number;
@@ -205,6 +206,7 @@ interface PublishedShareMetadata {
         readonly path: string;
     };
     readonly actions: readonly string[];
+    readonly expiryClamped?: boolean;
     readonly expiresAt: string;
     readonly display: {
         readonly filename?: string;
@@ -274,6 +276,7 @@ type ShareTarget = SharePublishTarget;
 interface TargetPublishInput {
     readonly source: Uint8Array;
     readonly filename: string;
+    readonly mediaType?: string;
     /** Additional files for a prefix resource; source remains the first file for compatibility. */
     readonly files?: readonly {
         readonly bytes: Uint8Array;
@@ -282,8 +285,8 @@ interface TargetPublishInput {
     }[];
     readonly target: ShareTarget;
     readonly expiresAt: Date;
+    readonly expiryWasExplicit?: boolean;
     readonly origin: string;
-    readonly mediaType?: string;
     readonly resourceKind?: "exact" | "prefix";
     readonly actions?: readonly ("read" | "list" | "edit")[];
     readonly notify?: boolean;
@@ -587,6 +590,29 @@ interface AddressedSharePublishOptions {
     readonly onDeliveryMaterial?: (input: PublishedShareDeliveryMaterial) => void;
     readonly authority: AddressedPublishAuthority;
 }
+type MailboxTarget = Extract<ShareTarget, {
+    readonly kind: "email" | "emailDomain";
+}>;
+/** The Policy/v2 credential commitment a share addressed to `target` must carry. */
+declare function addressedCredentialRequirement(target: MailboxTarget): PolicyCredentialRequirementV1;
+/** Facts every addressed-share check needs, available before any side effect. */
+type AddressedShareRequest = Pick<AddressedSharePublishOptions, "target" | "actions" | "policyActions" | "filename" | "deliveryEmail">;
+interface PreparedAddressedShare {
+    /** The canonical target the envelope's recipient matcher will carry. */
+    readonly target: Exclude<ShareTarget, {
+        readonly kind: "bearer";
+    }>;
+    /** Present for mailbox targets: the Policy/v2 commitment to pass to `publishAddressedShare`. */
+    readonly credentialRequirement?: PolicyCredentialRequirementV1;
+}
+/**
+ * Runs every argument and target check of `publishAddressedShare` that does
+ * not depend on stored content, and derives the credential commitment. It has
+ * no side effects, so senders call it before uploading content or publishing
+ * a location record; a refused share then leaves nothing behind.
+ */
+declare function prepareAddressedShare(request: AddressedShareRequest): PreparedAddressedShare;
+/** Canonical application-neutral Policy/v3 addressed publisher shared by browser and CLI. */
 declare function publishAddressedShare(options: AddressedSharePublishOptions): Promise<PublishedShare>;
 
 interface ShareCacheKey {
@@ -795,7 +821,11 @@ declare class ShareNotifyError extends Error {
     readonly code: "delivery-failed";
     constructor(message?: string);
 }
-/** Match a delivery address against the recipient constraint recorded when the share was created. */
+/**
+ * Match a delivery address against the recipient constraint recorded when the
+ * share was created. Both sides compare in canonical mailbox form, which is
+ * the only form the credential issuer accepts.
+ */
 declare function recipientMatchesShareRecord(record: SenderShareRecord, recipient: string): boolean;
 /**
  * Delivery is deliberately separate from publication. A failed notification
@@ -1058,6 +1088,12 @@ declare function resumeShareAuthorization<T>(input: {
 
 /** Fragment-only adapter for TinyCloud's public SharingService. */
 declare const NATIVE_SHARE_FRAGMENT_PARAMETER = "tc1";
+interface NativeShareResult {
+    readonly url: string;
+    readonly delegationCid: string;
+    readonly expiresAt: Date;
+    readonly spaceId: string;
+}
 interface NativeSharingService {
     generate(params: {
         readonly path: string;
@@ -1078,15 +1114,10 @@ declare function createNativeShare(sharing: NativeSharingService, input: {
     readonly path: string;
     readonly expiresAt: Date;
     readonly viewerOrigin: string;
-}): Promise<{
-    readonly url: string;
-    readonly delegationCid: string;
-    readonly expiresAt: Date;
-    readonly spaceId: string;
-}>;
+}): Promise<NativeShareResult>;
 /** Extract only a single tc1 fragment. Path/query/mixed legacy forms are refused. */
 declare function parseNativeShareUrl(value: string): string;
 /** Receive through the public SDK without creating another transport protocol. */
 declare function openNativeShare(sharing: NativeSharingService, link: string): Promise<unknown>;
 
-export { type AddressedOwnerRootInput, type AddressedOwnerRootReceipt, type AddressedPolicyRegistrationInput, type AddressedPolicyRegistrationReceipt, type AddressedPublishAuthority, type AddressedSharePublishOptions, type CreateOwnerDelegationParams, CredentialInvitationError, type CredentialInvitationErrorCode, type CredentialInvitationReceipt, type CredentialInvitationResult, DEFAULT_MAX_CONTENT_BLOB_BYTES, DEFAULT_MAX_SEALED_BLOB_BYTES, DEFAULT_SHARE_LIFETIME_MS, type DelegatedShareKey, EncryptedSenderShareHistory, type EncryptedShareHistoryStorage, MAX_CONTENT_BYTES, MemoryEncryptedShareHistoryStorage, MemorySenderShareKeyStorage, MemorySenderShareRecordStorage, MemoryShareCache, NATIVE_SHARE_FRAGMENT_PARAMETER, type NativeSharingService, OWNER_SHARE_REGISTRATION_DOMAIN, type OwnerDelegationPermission, type OwnerDelegationReceipt, type OwnerShareAction, type OwnerShareDecryption, type OwnerShareMatcher, type OwnerSharePolicyRegistration, type OwnerSharePolicyRegistrationReceipt, type OwnerSharePolicyV2, type ParsedAddressedEnvelope, type PublishedShare, type PublishedShareDeliveryMaterial, type PublishedShareMetadata, type RegisterOwnerSharePolicyParams, SHARE_CONTENT_LIMIT, SHARE_PUBLISH_RESULT_VERSION, SHARE_RESULT_VERSION, SHARE_V2_PROTOCOL, type SenderShareKeyStorage, type SenderShareRecord, type SenderShareRecordStorage, type SenderShareRevocationScope, SenderShareStore, type ShareAuthorizationAdapter, type ShareAuthorizationDenied, type ShareAuthorizationMethod, type ShareAuthorizationReady, type ShareAuthorizationRequired, type ShareAuthorizationResult, type ShareAuthorizedContent, type ShareCache, type ShareCacheEntry, type ShareCacheKey, type ShareCacheMetadata, type ShareDeliveryAdapter, type ShareErrorCode, type ShareErrorInfo, type ShareFetchOptions, type ShareHistoryView, type ShareInspection, type ShareMetadata, type ShareNodeTrust, ShareNotifyError, type ShareNotifyInput, type ShareNotifyResult, type ShareNotifyState, type SharePolicyChallenge, type SharePolicyPublishAdapter, type SharePolicyRootRevocation, type SharePolicySession, type SharePresentationMaterial, SharePublishError, type SharePublishErrorCode, type SharePublishOptions, type SharePublishTarget, type ShareReceiveAuthorizationRequired, ShareReceiveError, type ShareReceiveOutcome, type ShareReceiveResult, ShareRecipientClient, type ShareRecipientClientOptions, type ShareRevocationAdapter, type ShareRevocationResult, type ShareTarget, type SignedDelegation, type TargetPublishAdapter, type TargetPublishInput, type TargetPublishOutcome, authorizationMethodForTarget, authorizeShare, canonicalOwnerSharePolicy, claimShare, computeOwnerShareRegistrationCid, createAddressedAuthorization, createDelegatedShareKey, createNativeShare, createPolicyEnforcementDelegation, createShareV2HolderBindingArtifact, deliverCredentialInvitation, historyRecordForPublishedShare, inspectShare, listShares, normalizeShareTarget, notifyShare, openNativeShare, parseAddressedEnvelope, parseNativeShareUrl, publishAddressedShare, publishPolicyShare, publishTargetShare, receiveShare, recipientMatchesShareRecord, redactPublishedShare, restoreDelegatedShareKey, resumeShareAuthorization, revokeShare, showShare, targetAuthorizationMethod, toShareErrorInfo, validateOwnerSharePolicyRegistration, validateOwnerSharePolicyRegistrationBytes };
+export { type AddressedOwnerRootInput, type AddressedOwnerRootReceipt, type AddressedPolicyRegistrationInput, type AddressedPolicyRegistrationReceipt, type AddressedPublishAuthority, type AddressedSharePublishOptions, type AddressedShareRequest, type CreateOwnerDelegationParams, CredentialInvitationError, type CredentialInvitationErrorCode, type CredentialInvitationReceipt, type CredentialInvitationResult, DEFAULT_MAX_CONTENT_BLOB_BYTES, DEFAULT_MAX_SEALED_BLOB_BYTES, DEFAULT_SHARE_LIFETIME_MS, type DelegatedShareKey, EncryptedSenderShareHistory, type EncryptedShareHistoryStorage, MAX_CONTENT_BYTES, MemoryEncryptedShareHistoryStorage, MemorySenderShareKeyStorage, MemorySenderShareRecordStorage, MemoryShareCache, NATIVE_SHARE_FRAGMENT_PARAMETER, type NativeShareResult, type NativeSharingService, OWNER_SHARE_REGISTRATION_DOMAIN, type OwnerDelegationPermission, type OwnerDelegationReceipt, type OwnerShareAction, type OwnerShareDecryption, type OwnerShareMatcher, type OwnerSharePolicyRegistration, type OwnerSharePolicyRegistrationReceipt, type OwnerSharePolicyV2, type ParsedAddressedEnvelope, type PreparedAddressedShare, type PublishedShare, type PublishedShareDeliveryMaterial, type PublishedShareMetadata, type RegisterOwnerSharePolicyParams, SHARE_CONTENT_LIMIT, SHARE_PUBLISH_RESULT_VERSION, SHARE_RESULT_VERSION, SHARE_V2_PROTOCOL, type SenderShareKeyStorage, type SenderShareRecord, type SenderShareRecordStorage, type SenderShareRevocationScope, SenderShareStore, type ShareAuthorizationAdapter, type ShareAuthorizationDenied, type ShareAuthorizationMethod, type ShareAuthorizationReady, type ShareAuthorizationRequired, type ShareAuthorizationResult, type ShareAuthorizedContent, type ShareCache, type ShareCacheEntry, type ShareCacheKey, type ShareCacheMetadata, type ShareDeliveryAdapter, type ShareErrorCode, type ShareErrorInfo, type ShareFetchOptions, type ShareHistoryView, type ShareInspection, type ShareMetadata, type ShareNodeTrust, ShareNotifyError, type ShareNotifyInput, type ShareNotifyResult, type ShareNotifyState, type SharePolicyChallenge, type SharePolicyPublishAdapter, type SharePolicyRootRevocation, type SharePolicySession, type SharePresentationMaterial, SharePublishError, type SharePublishErrorCode, type SharePublishOptions, type SharePublishTarget, type ShareReceiveAuthorizationRequired, ShareReceiveError, type ShareReceiveOutcome, type ShareReceiveResult, ShareRecipientClient, type ShareRecipientClientOptions, type ShareRevocationAdapter, type ShareRevocationResult, type ShareTarget, type SignedDelegation, type TargetPublishAdapter, type TargetPublishInput, type TargetPublishOutcome, addressedCredentialRequirement, authorizationMethodForTarget, authorizeShare, canonicalOwnerSharePolicy, claimShare, computeOwnerShareRegistrationCid, createAddressedAuthorization, createDelegatedShareKey, createNativeShare, createPolicyEnforcementDelegation, createShareV2HolderBindingArtifact, deliverCredentialInvitation, historyRecordForPublishedShare, inspectShare, listShares, normalizeShareTarget, notifyShare, openNativeShare, parseAddressedEnvelope, parseNativeShareUrl, prepareAddressedShare, publishAddressedShare, publishPolicyShare, publishTargetShare, receiveShare, recipientMatchesShareRecord, redactPublishedShare, restoreDelegatedShareKey, resumeShareAuthorization, revokeShare, showShare, targetAuthorizationMethod, toShareErrorInfo, validateOwnerSharePolicyRegistration, validateOwnerSharePolicyRegistrationBytes };

package/dist/index.js

@@ -5685,6 +5685,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");
@@ -6020,6 +6035,7 @@ function redactPublishedShare(result) {
       target: { ...result.metadata.target },
       resource: { ...result.metadata.resource },
       actions: [...result.metadata.actions],
+      ...result.metadata.expiryClamped === void 0 ? {} : { expiryClamped: result.metadata.expiryClamped },
       expiresAt: result.metadata.expiresAt,
       display: { ...result.metadata.display }
     }
@@ -6429,12 +6445,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(":");
@@ -6464,12 +6474,13 @@ 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);
@@ -6532,6 +6543,7 @@ async function publishTargetShare(input) {
     ...input.actions === void 0 ? {} : { actions: input.actions },
     target,
     expiresAt,
+    expiryWasExplicit: input.expiryWasExplicit ?? input.expiresAt !== void 0,
     origin: input.origin,
     ...input.notify === void 0 ? {} : { notify: input.notify }
   });
@@ -6555,9 +6567,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");
@@ -6650,23 +6660,55 @@ 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(sha2563(textEncoder.encode(canonicalize(expected)))) !== commitment.requirementDigest) throw new TypeError("credential requirement is not bound to the email domain");
+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(sha2563(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) {
+  if (request.filename.length === 0 || request.filename === "." || request.filename === ".." || /[/\\\u0000-\u001f\u007f]/.test(request.filename)) 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 === "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(options) {
   assertSafeInput(options);
-  const target = normalizeShareTarget(options.target);
-  if (target.kind === "bearer") throw new TypeError("addressed target is required");
-  if (target.kind === "emailDomain") assertEmailDomainPolicy(options, target.domain);
+  const { target } = prepareAddressedShare(options);
+  if (target.kind !== "recipientDid") assertMailboxCommitment(options.credentialRequirement, target);
   const expiry = rfc3339Seconds(options.expiresAt);
   const matcher = targetMatcher(target);
   const capabilities = sortCanonical([
@@ -7777,17 +7819,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;
@@ -7796,7 +7841,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;
@@ -8479,7 +8524,11 @@ function canonicalViewerUrl(viewerOrigin) {
 async function createNativeShare(sharing, input) {
   if (!input.path || input.path.startsWith("/") || input.path.endsWith("/") || input.path.includes("..") || input.path.includes("//")) throw new TypeError("native share path must be one canonical TinyCloud KV key");
   const generated = await sharing.generate({ path: input.path, actions: ["tinycloud.kv/get"], expiry: input.expiresAt });
-  if (generated.ok !== true) throw new Error(typeof generated.error?.message === "string" ? generated.error.message : "TinyCloud sharing service rejected delegation generation");
+  if (generated.ok !== true) {
+    const error = new Error(typeof generated.error?.message === "string" ? generated.error.message : "TinyCloud sharing service rejected delegation generation");
+    if (typeof generated.error?.code === "string") Object.assign(error, { code: generated.error.code });
+    throw error;
+  }
   if (typeof generated.data?.token !== "string" || typeof generated.data.delegation?.cid !== "string" || !(generated.data.expiresAt instanceof Date)) throw new Error("TinyCloud sharing service returned incomplete delegation metadata");
   const delegation = sharing.decodeLink(generated.data.token);
   if (typeof delegation.spaceId !== "string" || delegation.spaceId.length === 0 || typeof delegation.path !== "string" || delegation.path.length === 0) throw new Error("TinyCloud sharing service returned a non-canonical delegation authority");
@@ -8520,6 +8569,7 @@ export {
   SharePublishError,
   ShareReceiveError,
   ShareRecipientClient,
+  addressedCredentialRequirement,
   authorizationMethodForTarget,
   authorizeShare,
   canonicalOwnerSharePolicy,
@@ -8542,6 +8592,7 @@ export {
   openNativeShare,
   parseAddressedEnvelope,
   parseNativeShareUrl,
+  prepareAddressedShare,
   publishAddressedShare,
   publishPolicyShare,
   publishTargetShare,