@plane31/blind-relay 0.1.3 → 0.3.0

package/src/transport.ts

@@ -19,6 +19,52 @@ export interface ResolvedAccount {
   readonly certificate: Uint8Array;
   /** When the account's key changed through a reset: the receipt that proves it. */
   readonly resetReceipt?: Uint8Array | undefined;
+  /** When the account's key changed through successions (revision 9): the first page of the chain from the root, each link with the successor's certificate, oldest first. */
+  readonly successions?: readonly SuccessionLink[] | undefined;
+  /** Set when `successions` is not the whole chain: the generation to continue from with `getSuccessions`. */
+  readonly successionsNext?: bigint | undefined;
+  /** With a non-empty chain: a certificate under the root key (the one the first succession replaced), so a peer can verify what that key signed. */
+  readonly rootCertificate?: Uint8Array | undefined;
+}
+
+/** One link of an account's succession chain: the type 9 document and the certificate it binds. */
+export interface SuccessionLink {
+  readonly wire: Uint8Array;
+  readonly certificate: Uint8Array;
+}
+
+export interface SuccessionPage {
+  readonly successions: readonly SuccessionLink[];
+  /** On the first page of a non-empty chain: a certificate under the root key. */
+  readonly rootCertificate?: Uint8Array | undefined;
+  /** The generation to ask after for the next page; absent when the chain ends here. */
+  readonly nextGeneration?: bigint | undefined;
+}
+
+/** One circle of the authenticated account as the host lists it for bootstrap (amendment A1, section 5). Host-trusted. */
+export interface CircleListing {
+  readonly circleId: Uint8Array;
+  readonly ownerAccountId: Uint8Array;
+  readonly role: "owner" | "member" | "pending";
+  /** The current snapshot; absent for a closed circle. */
+  readonly snapshot: Uint8Array | undefined;
+  /** The account's sharing preference the host holds; absent when none was ever set (disabled). */
+  readonly enabled: boolean | undefined;
+  readonly preferenceRevision: bigint;
+}
+
+export interface CirclePage {
+  readonly circles: readonly CircleListing[];
+  /** The cursor for the next page; absent on the last page. */
+  readonly cursor?: string | undefined;
+}
+
+export interface PreferenceOutcome {
+  readonly status: "COMMITTED" | "ALREADY_COMMITTED" | "CONFLICT" | "UNAUTHORIZED" | "RETRYABLE";
+  /** The revision the host now holds (the new one on success, the current one on conflict). */
+  readonly revision: bigint;
+  /** On CONFLICT: the value the host holds at that revision. */
+  readonly enabled?: boolean | undefined;
 }
 
 export interface JoinRequest {
@@ -41,7 +87,8 @@ export interface Directory {
     newCertificate: Uint8Array;
     newVault: Uint8Array;
   }): Promise<MutationOutcome>;
-  registerAccount(input: { certificate: Uint8Array; vault: Uint8Array }): Promise<MutationOutcome>;
+  /** `vault` is absent for an account on a recovery-only profile without a recovery provider. */
+  registerAccount(input: { certificate: Uint8Array; vault: Uint8Array | undefined }): Promise<MutationOutcome>;
   getVault(accountName: string): Promise<Uint8Array | undefined>;
   publishVault(input: { expectedRevision: bigint; expectedHash: Uint8Array | undefined; newVault: Uint8Array }): Promise<MutationOutcome>;
   getCircle(circleId: Uint8Array): Promise<Uint8Array | undefined>;
@@ -55,10 +102,30 @@ export interface Directory {
     accountName: string;
     expectedOldIdentityId: Uint8Array;
     newCertificate: Uint8Array;
-    newVault: Uint8Array;
+    newVault: Uint8Array | undefined;
     resetId: Uint8Array;
     reauthProof: Uint8Array;
   }): Promise<MutationOutcome & { receipt?: Uint8Array | undefined }>;
+  /**
+   * Account recovery (amendment A1): commit a prepared replacement. `ALREADY_COMMITTED` with the
+   * original document for a repeated `successionId` with identical bytes is answered before any
+   * authorization check; `CONFLICT` carries the current certificate; `UNAUTHORIZED` covers a
+   * missing, expired or mismatched authorization and a known id with different bytes.
+   */
+  succeedAccount(input: {
+    accountName: string;
+    expectedCertificateHash: Uint8Array;
+    newCertificate: Uint8Array;
+    newVault: Uint8Array | undefined;
+    successionId: Uint8Array;
+    authorization: Uint8Array;
+  }): Promise<MutationOutcome & { succession?: Uint8Array | undefined }>;
+  /** One page of an account's succession chain, in generation order, links whose new generation exceeds `afterGeneration`. */
+  getSuccessions(accountId: Uint8Array, afterGeneration: bigint, limit: number): Promise<SuccessionPage>;
+  /** One page of the authenticated account's circles, for bootstrap without a vault. */
+  listCircles(cursor: string | undefined): Promise<CirclePage>;
+  /** Compare-and-swap on the per-circle preference revision the host keeps for the authenticated account. */
+  setSharingPreference(circleId: Uint8Array, enabled: boolean, expectedRevision: bigint): Promise<PreferenceOutcome>;
 }
 
 export interface EpochBundle {