@tinycloud/share-sdk 1.4.4-beta.0 → 1.4.4

package/dist/index.d.cts

@@ -141,10 +141,29 @@ declare function deliverCredentialInvitation(input: {
     readonly signal?: AbortSignal;
 }): Promise<CredentialInvitationResult>;
 
+/**
+ * One root of an addressed share after `revokeShare`. A `left-live` root is
+ * only ever the policy-authority root, whose audience is a policy digest DID
+ * with no key: it cannot authorize anything once the enforcement root is
+ * revoked, and it lapses at `expiresAt`.
+ */
+type ShareRootRevocationState = {
+    readonly rootCid: string;
+    readonly targetRole: "policy-authority" | "policy-enforcement";
+    readonly state: "revoked";
+} | {
+    readonly rootCid: string;
+    readonly targetRole: "policy-authority";
+    readonly state: "left-live";
+    readonly expiresAt: string;
+};
 type ShareRevocationResult = {
     readonly state: "revoked";
     readonly target: "bearer" | "recipientDid" | "email" | "emailDomain";
+    /** The bearer delegation; for an addressed share its enforcement root (its policy root when the record has no enforcement root). */
     readonly delegationCid: string;
+    /** Addressed shares: every root the share created, with what this revocation did to it. Recipient access has ended. */
+    readonly roots?: readonly ShareRootRevocationState[];
     readonly revokedAt: string;
 } | {
     readonly state: "unsupported";
@@ -172,16 +191,47 @@ interface ShareRevocationAdapter {
     /**
      * Addressed Policy/v3 authority uses the Node's signed root-revocation
      * endpoint. The Node checks that root for active sessions, new admission,
-     * and delivery; this is not a separate share authority plane.
+     * and delivery; this is not a separate share authority plane. It resolves
+     * when the root is revoked, including when the Node already holds a
+     * revocation for it, and rejects otherwise. For the policy-authority root
+     * only, it may resolve `"left-live"` instead of revoking it (for example
+     * when revoking it would cost the owner another wallet approval).
      */
-    revokePolicyRoot?(input: SharePolicyRootRevocation): Promise<void>;
+    revokePolicyRoot?(input: SharePolicyRootRevocation): Promise<void | "left-live">;
+}
+/** A root an addressed revocation did not end. */
+interface ShareRootRevocationFailure {
+    readonly rootCid: string;
+    readonly targetRole: SharePolicyRootRevocation["targetRole"];
+    readonly error: unknown;
+}
+/**
+ * An addressed revocation did not finish: a root failed, or only the
+ * policy-authority root was dealt with. `revoked` names the roots that were
+ * revoked; if it is not empty, recipient access has ended, since every
+ * recipient request needs both roots. The share record is not marked
+ * revoked, so the caller can retry.
+ */
+declare class ShareRevocationIncompleteError extends Error {
+    readonly revoked: readonly string[];
+    readonly failed: readonly ShareRootRevocationFailure[];
+    constructor(revoked: readonly string[], failed: readonly ShareRootRevocationFailure[]);
 }
-/** Revoke the native bearer delegation or the selected signed Policy/v3 root. */
+/**
+ * Revoke a share. A bearer share revokes the delegation `scope` selects. An
+ * addressed share asks the adapter for every root it created, the
+ * enforcement root and then the policy root, whatever `scope` says; the
+ * adapter may leave the keyless policy-authority root live. It succeeds only
+ * when no root failed and at least one was revoked (so recipient access has
+ * ended); otherwise it throws {@link ShareRevocationIncompleteError} after
+ * trying every root.
+ */
 declare function revokeShare(input: {
     readonly record: SenderShareRecord;
     /** Optional durable store; successful revocation is persisted before return. */
     readonly records?: SenderShareRecordStorage;
     readonly adapter?: ShareRevocationAdapter;
+    /** Bearer shares only. */
     readonly scope?: "direct" | "ancestor";
     readonly now?: () => Date;
 }): Promise<ShareRevocationResult>;
@@ -372,4 +422,4 @@ declare function assertArtifactBinding(view: ArtifactBindingView, expected?: Exp
  */
 declare function verifyArtifactShare(envelope: ShareEnvelopeV3, options: VerifyArtifactShareOptions): ArtifactPin | undefined;
 
-export { type ArtifactBindingView, ArtifactPinError, type ArtifactPinErrorCode, CredentialInvitationError, type CredentialInvitationErrorCode, type CredentialInvitationReceipt, type CredentialInvitationResult, type ExpectedArtifact, MemoryShareCache, NATIVE_SHARE_FRAGMENT_PARAMETER, type NativeShareResult, type NativeSharingService, type ParsedAddressedEnvelope, SHARE_V2_PROTOCOL, SenderShareRecord, SenderShareRecordStorage, ShareAuthorizationAdapter, ShareAuthorizationResult, type ShareCache, type ShareCacheEntry, type ShareCacheKey, type ShareCacheMetadata, type ShareDeliveryAdapter, type ShareHistoryView, ShareNotifyError, type ShareNotifyInput, type ShareNotifyResult, type ShareNotifyState, type SharePolicyPublishAdapter, type SharePolicyRootRevocation, type ShareRevocationAdapter, type ShareRevocationResult, ShareTarget, TargetPublishInput, TargetPublishOutcome, type VerifyArtifactShareOptions, artifactBindingView, assertArtifactBinding, canonicalShareFilename, claimShare, createNativeShare, createShareV2HolderBindingArtifact, deliverCredentialInvitation, hasUnsafeFilenameCodePoint, listShares, notifyShare, openNativeShare, parseAddressedEnvelope, parseNativeShareUrl, publishPolicyShare, recipientMatchesShareRecord, resumeShareAuthorization, revokeShare, shareDeliveryWindowExpiresAt, showShare, verifyArtifactShare };
+export { type ArtifactBindingView, ArtifactPinError, type ArtifactPinErrorCode, CredentialInvitationError, type CredentialInvitationErrorCode, type CredentialInvitationReceipt, type CredentialInvitationResult, type ExpectedArtifact, MemoryShareCache, NATIVE_SHARE_FRAGMENT_PARAMETER, type NativeShareResult, type NativeSharingService, type ParsedAddressedEnvelope, SHARE_V2_PROTOCOL, SenderShareRecord, SenderShareRecordStorage, ShareAuthorizationAdapter, ShareAuthorizationResult, type ShareCache, type ShareCacheEntry, type ShareCacheKey, type ShareCacheMetadata, type ShareDeliveryAdapter, type ShareHistoryView, ShareNotifyError, type ShareNotifyInput, type ShareNotifyResult, type ShareNotifyState, type SharePolicyPublishAdapter, type SharePolicyRootRevocation, type ShareRevocationAdapter, ShareRevocationIncompleteError, type ShareRevocationResult, type ShareRootRevocationFailure, type ShareRootRevocationState, ShareTarget, TargetPublishInput, TargetPublishOutcome, type VerifyArtifactShareOptions, artifactBindingView, assertArtifactBinding, canonicalShareFilename, claimShare, createNativeShare, createShareV2HolderBindingArtifact, deliverCredentialInvitation, hasUnsafeFilenameCodePoint, listShares, notifyShare, openNativeShare, parseAddressedEnvelope, parseNativeShareUrl, publishPolicyShare, recipientMatchesShareRecord, resumeShareAuthorization, revokeShare, shareDeliveryWindowExpiresAt, showShare, verifyArtifactShare };

package/dist/index.d.ts

@@ -141,10 +141,29 @@ declare function deliverCredentialInvitation(input: {
     readonly signal?: AbortSignal;
 }): Promise<CredentialInvitationResult>;
 
+/**
+ * One root of an addressed share after `revokeShare`. A `left-live` root is
+ * only ever the policy-authority root, whose audience is a policy digest DID
+ * with no key: it cannot authorize anything once the enforcement root is
+ * revoked, and it lapses at `expiresAt`.
+ */
+type ShareRootRevocationState = {
+    readonly rootCid: string;
+    readonly targetRole: "policy-authority" | "policy-enforcement";
+    readonly state: "revoked";
+} | {
+    readonly rootCid: string;
+    readonly targetRole: "policy-authority";
+    readonly state: "left-live";
+    readonly expiresAt: string;
+};
 type ShareRevocationResult = {
     readonly state: "revoked";
     readonly target: "bearer" | "recipientDid" | "email" | "emailDomain";
+    /** The bearer delegation; for an addressed share its enforcement root (its policy root when the record has no enforcement root). */
     readonly delegationCid: string;
+    /** Addressed shares: every root the share created, with what this revocation did to it. Recipient access has ended. */
+    readonly roots?: readonly ShareRootRevocationState[];
     readonly revokedAt: string;
 } | {
     readonly state: "unsupported";
@@ -172,16 +191,47 @@ interface ShareRevocationAdapter {
     /**
      * Addressed Policy/v3 authority uses the Node's signed root-revocation
      * endpoint. The Node checks that root for active sessions, new admission,
-     * and delivery; this is not a separate share authority plane.
+     * and delivery; this is not a separate share authority plane. It resolves
+     * when the root is revoked, including when the Node already holds a
+     * revocation for it, and rejects otherwise. For the policy-authority root
+     * only, it may resolve `"left-live"` instead of revoking it (for example
+     * when revoking it would cost the owner another wallet approval).
      */
-    revokePolicyRoot?(input: SharePolicyRootRevocation): Promise<void>;
+    revokePolicyRoot?(input: SharePolicyRootRevocation): Promise<void | "left-live">;
+}
+/** A root an addressed revocation did not end. */
+interface ShareRootRevocationFailure {
+    readonly rootCid: string;
+    readonly targetRole: SharePolicyRootRevocation["targetRole"];
+    readonly error: unknown;
+}
+/**
+ * An addressed revocation did not finish: a root failed, or only the
+ * policy-authority root was dealt with. `revoked` names the roots that were
+ * revoked; if it is not empty, recipient access has ended, since every
+ * recipient request needs both roots. The share record is not marked
+ * revoked, so the caller can retry.
+ */
+declare class ShareRevocationIncompleteError extends Error {
+    readonly revoked: readonly string[];
+    readonly failed: readonly ShareRootRevocationFailure[];
+    constructor(revoked: readonly string[], failed: readonly ShareRootRevocationFailure[]);
 }
-/** Revoke the native bearer delegation or the selected signed Policy/v3 root. */
+/**
+ * Revoke a share. A bearer share revokes the delegation `scope` selects. An
+ * addressed share asks the adapter for every root it created, the
+ * enforcement root and then the policy root, whatever `scope` says; the
+ * adapter may leave the keyless policy-authority root live. It succeeds only
+ * when no root failed and at least one was revoked (so recipient access has
+ * ended); otherwise it throws {@link ShareRevocationIncompleteError} after
+ * trying every root.
+ */
 declare function revokeShare(input: {
     readonly record: SenderShareRecord;
     /** Optional durable store; successful revocation is persisted before return. */
     readonly records?: SenderShareRecordStorage;
     readonly adapter?: ShareRevocationAdapter;
+    /** Bearer shares only. */
     readonly scope?: "direct" | "ancestor";
     readonly now?: () => Date;
 }): Promise<ShareRevocationResult>;
@@ -372,4 +422,4 @@ declare function assertArtifactBinding(view: ArtifactBindingView, expected?: Exp
  */
 declare function verifyArtifactShare(envelope: ShareEnvelopeV3, options: VerifyArtifactShareOptions): ArtifactPin | undefined;
 
-export { type ArtifactBindingView, ArtifactPinError, type ArtifactPinErrorCode, CredentialInvitationError, type CredentialInvitationErrorCode, type CredentialInvitationReceipt, type CredentialInvitationResult, type ExpectedArtifact, MemoryShareCache, NATIVE_SHARE_FRAGMENT_PARAMETER, type NativeShareResult, type NativeSharingService, type ParsedAddressedEnvelope, SHARE_V2_PROTOCOL, SenderShareRecord, SenderShareRecordStorage, ShareAuthorizationAdapter, ShareAuthorizationResult, type ShareCache, type ShareCacheEntry, type ShareCacheKey, type ShareCacheMetadata, type ShareDeliveryAdapter, type ShareHistoryView, ShareNotifyError, type ShareNotifyInput, type ShareNotifyResult, type ShareNotifyState, type SharePolicyPublishAdapter, type SharePolicyRootRevocation, type ShareRevocationAdapter, type ShareRevocationResult, ShareTarget, TargetPublishInput, TargetPublishOutcome, type VerifyArtifactShareOptions, artifactBindingView, assertArtifactBinding, canonicalShareFilename, claimShare, createNativeShare, createShareV2HolderBindingArtifact, deliverCredentialInvitation, hasUnsafeFilenameCodePoint, listShares, notifyShare, openNativeShare, parseAddressedEnvelope, parseNativeShareUrl, publishPolicyShare, recipientMatchesShareRecord, resumeShareAuthorization, revokeShare, shareDeliveryWindowExpiresAt, showShare, verifyArtifactShare };
+export { type ArtifactBindingView, ArtifactPinError, type ArtifactPinErrorCode, CredentialInvitationError, type CredentialInvitationErrorCode, type CredentialInvitationReceipt, type CredentialInvitationResult, type ExpectedArtifact, MemoryShareCache, NATIVE_SHARE_FRAGMENT_PARAMETER, type NativeShareResult, type NativeSharingService, type ParsedAddressedEnvelope, SHARE_V2_PROTOCOL, SenderShareRecord, SenderShareRecordStorage, ShareAuthorizationAdapter, ShareAuthorizationResult, type ShareCache, type ShareCacheEntry, type ShareCacheKey, type ShareCacheMetadata, type ShareDeliveryAdapter, type ShareHistoryView, ShareNotifyError, type ShareNotifyInput, type ShareNotifyResult, type ShareNotifyState, type SharePolicyPublishAdapter, type SharePolicyRootRevocation, type ShareRevocationAdapter, ShareRevocationIncompleteError, type ShareRevocationResult, type ShareRootRevocationFailure, type ShareRootRevocationState, ShareTarget, TargetPublishInput, TargetPublishOutcome, type VerifyArtifactShareOptions, artifactBindingView, assertArtifactBinding, canonicalShareFilename, claimShare, createNativeShare, createShareV2HolderBindingArtifact, deliverCredentialInvitation, hasUnsafeFilenameCodePoint, listShares, notifyShare, openNativeShare, parseAddressedEnvelope, parseNativeShareUrl, publishPolicyShare, recipientMatchesShareRecord, resumeShareAuthorization, revokeShare, shareDeliveryWindowExpiresAt, showShare, verifyArtifactShare };

package/dist/index.js

@@ -8806,6 +8806,14 @@ async function deliverCredentialInvitation(input) {
 }
 
 // src/lifecycle.ts
+var ShareRevocationIncompleteError = class extends Error {
+  constructor(revoked, failed) {
+    super(`share revocation incomplete: ${failed.map((failure) => failure.targetRole).join(", ")} not revoked`);
+    this.revoked = revoked;
+    this.failed = failed;
+    this.name = "ShareRevocationIncompleteError";
+  }
+};
 function targetKind2(record) {
   if (record.targetKind !== void 0) return record.targetKind;
   return record.recipientMatcher.kind === "exactEmail" ? "email" : record.recipientMatcher.kind === "emailDomain" ? "emailDomain" : record.recipientMatcher.kind === "recipientDid" ? "recipientDid" : "bearer";
@@ -8821,22 +8829,49 @@ function policyNodeAudience(record) {
 async function revokeShare(input) {
   const target = targetKind2(input.record);
   if (input.adapter === void 0) return { state: "unsupported", target, reason: "node revocation authority is required", code: "unsupported-target" };
-  const scope = input.scope ?? "direct";
-  const delegationCid = scope === "ancestor" ? input.record.ownerDelegationCid : input.record.enforcementDelegationCid;
-  if (delegationCid === void 0) return { state: "unsupported", target, reason: "share has no node-enforced delegation receipt", code: "unsupported-target" };
+  let delegationCid;
+  let roots;
   if (target === "bearer") {
+    const scope = input.scope ?? "direct";
+    const selected = scope === "ancestor" ? input.record.ownerDelegationCid : input.record.enforcementDelegationCid;
+    if (selected === void 0) return { state: "unsupported", target, reason: "share has no node-enforced delegation receipt", code: "unsupported-target" };
     if (input.adapter.revokeDelegation === void 0) return { state: "unsupported", target, reason: "native delegation revocation authority is required", code: "unsupported-target" };
-    await input.adapter.revokeDelegation({ delegationCid, scope, record: input.record });
+    await input.adapter.revokeDelegation({ delegationCid: selected, scope, record: input.record });
+    delegationCid = selected;
   } else {
-    if (input.record.ownerDid === void 0) return { state: "unsupported", target, reason: "share has no Policy/v3 owner receipt", code: "unsupported-target" };
-    if (input.adapter.revokePolicyRoot === void 0) return { state: "unsupported", target, reason: "Policy/v3 root revocation authority is required", code: "unsupported-target" };
-    await input.adapter.revokePolicyRoot({
-      rootCid: delegationCid,
-      targetRole: scope === "ancestor" ? "policy-authority" : "policy-enforcement",
-      ownerDid: input.record.ownerDid,
-      nodeOrigin: input.record.target.origin,
-      nodeAudience: policyNodeAudience(input.record)
-    });
+    const requests = [
+      [input.record.enforcementDelegationCid, "policy-enforcement"],
+      [input.record.ownerDelegationCid, "policy-authority"]
+    ].flatMap(([rootCid, targetRole]) => rootCid === void 0 ? [] : [{ rootCid, targetRole }]);
+    const first = requests[0];
+    if (first === void 0) return { state: "unsupported", target, reason: "share has no node-enforced delegation receipt", code: "unsupported-target" };
+    const ownerDid = input.record.ownerDid;
+    if (ownerDid === void 0) return { state: "unsupported", target, reason: "share has no Policy/v3 owner receipt", code: "unsupported-target" };
+    const revokePolicyRoot = input.adapter.revokePolicyRoot;
+    if (revokePolicyRoot === void 0) return { state: "unsupported", target, reason: "Policy/v3 root revocation authority is required", code: "unsupported-target" };
+    const nodeAudience = policyNodeAudience(input.record);
+    roots = [];
+    const failed = [];
+    for (const request of requests) {
+      try {
+        const outcome = await revokePolicyRoot({ ...request, ownerDid, nodeOrigin: input.record.target.origin, nodeAudience });
+        if (outcome === "left-live") {
+          if (request.targetRole !== "policy-authority") throw new Error("the enforcement root cannot be left live");
+          roots.push({ rootCid: request.rootCid, targetRole: "policy-authority", state: "left-live", expiresAt: input.record.expiresAt });
+        } else if (outcome === void 0) {
+          roots.push({ ...request, state: "revoked" });
+        } else {
+          throw new Error("root revocation returned an unknown outcome");
+        }
+      } catch (error) {
+        failed.push({ ...request, error });
+      }
+    }
+    const revoked = roots.flatMap((root) => root.state === "revoked" ? [root.rootCid] : []);
+    if (failed.length > 0 || revoked.length === 0) {
+      throw new ShareRevocationIncompleteError(revoked, failed.length > 0 ? failed : roots.map((root) => ({ rootCid: root.rootCid, targetRole: root.targetRole, error: new Error("no root was revoked") })));
+    }
+    delegationCid = first.rootCid;
   }
   let revokedAt = input.record.revokedAt ?? (input.now?.() ?? /* @__PURE__ */ new Date()).toISOString();
   if (input.records?.update !== void 0) {
@@ -8847,7 +8882,7 @@ async function revokeShare(input) {
     revokedAt = latest?.revokedAt ?? revokedAt;
     await input.records.put({ ...latest ?? input.record, revokedAt });
   }
-  return { state: "revoked", target, delegationCid, revokedAt };
+  return { state: "revoked", target, delegationCid, ...roots === void 0 ? {} : { roots }, revokedAt };
 }
 function redactRecord(record, revealLink, link) {
   const matcher = record.recipientMatcher;
@@ -9436,6 +9471,7 @@ export {
   SharePublishError,
   ShareReceiveError,
   ShareRecipientClient,
+  ShareRevocationIncompleteError,
   addressedCredentialRequirement,
   addressedShareBodyUpperBound,
   artifactBindingView,