@plane31/blind-relay 0.1.3 → 0.2.0

package/src/codec.ts

@@ -69,6 +69,8 @@ export enum DocumentType {
   EncryptedRecord = 4,
   AccountVault = 6,
   AccountResetReceipt = 7,
+  /** Revision 9 (amendment A1): the host's authority binds an account to new keys with continuity of its relationships. */
+  AccountSuccession = 9,
   ResetKeyList = 8
 }
 
@@ -136,6 +138,27 @@ export interface AccountResetReceipt {
   readonly authorityKeyId: Uint8Array;
 }
 
+/**
+ * Type 9. The transition (every field but the last two and the signature) says what happened to
+ * the account; the attestation (`issuedAt`, `authorityKeyId`, the signature) says who vouched for
+ * it. Two documents with one transition are one succession.
+ */
+export interface AccountSuccession {
+  readonly type: DocumentType.AccountSuccession;
+  readonly accountName: string;
+  readonly accountId: Uint8Array;
+  readonly previousIdentityId: Uint8Array;
+  readonly newIdentityId: Uint8Array;
+  readonly previousGeneration: bigint;
+  readonly newGeneration: bigint;
+  readonly newCertificateHash: Uint8Array;
+  readonly successionId: Uint8Array;
+  readonly issuedAt: bigint;
+  readonly authorityKeyId: Uint8Array;
+}
+
+export const SUCCESSION_WIRE_BYTES_WITHOUT_NAME = 251;
+
 export interface ResetKeyEntry {
   readonly keyId: Uint8Array;
   readonly publicKey: Uint8Array;
@@ -149,7 +172,7 @@ export interface ResetKeyList {
   readonly keys: readonly ResetKeyEntry[];
 }
 
-export type SignedDocument = AccountDevice | CircleSnapshot | EpochManifest | EncryptedRecord | AccountResetReceipt | ResetKeyList;
+export type SignedDocument = AccountDevice | CircleSnapshot | EpochManifest | EncryptedRecord | AccountResetReceipt | ResetKeyList | AccountSuccession;
 
 /** A parsed signed document together with the exact body and signature bytes. */
 export type Parsed<T extends SignedDocument = SignedDocument> = T & {
@@ -164,6 +187,7 @@ export const LABEL_BY_TYPE: Readonly<Record<number, Label>> = {
   [DocumentType.EpochManifest]: "epoch-sig",
   [DocumentType.EncryptedRecord]: "record-sig",
   [DocumentType.AccountResetReceipt]: "reset-sig",
+  [DocumentType.AccountSuccession]: "succession-sig",
   [DocumentType.ResetKeyList]: "reset-keys-sig"
 };
 
@@ -268,6 +292,23 @@ export function parseDocument(wire: Uint8Array): Parsed {
       fields = { type, accountName, oldIdentityId, newIdentityId, resetId, issuedAt, authorityKeyId };
       break;
     }
+    case DocumentType.AccountSuccession: {
+      const accountName = r.name();
+      const accountId = r.take(HASH_BYTES);
+      const previousIdentityId = r.take(HASH_BYTES);
+      const newIdentityId = r.take(HASH_BYTES);
+      const previousGeneration = r.u64();
+      const newGeneration = r.u64();
+      const newCertificateHash = r.take(HASH_BYTES);
+      const successionId = r.take(16);
+      const issuedAt = r.u64();
+      const authorityKeyId = r.take(16);
+      if (equalBytes(previousIdentityId, newIdentityId)) throw malformed(stage, "previous and new identity equal");
+      if (previousGeneration < 1n || newGeneration !== previousGeneration + 1n) throw malformed(stage, "new generation must be previous plus one");
+      if (successionId.every((b) => b === 0)) throw malformed(stage, "succession id zero");
+      fields = { type, accountName, accountId, previousIdentityId, newIdentityId, previousGeneration, newGeneration, newCertificateHash, successionId, issuedAt, authorityKeyId };
+      break;
+    }
     case DocumentType.ResetKeyList: {
       const version = r.u64();
       const issuedAt = r.u64();
@@ -469,6 +510,28 @@ export function buildResetReceipt(f: Omit<AccountResetReceipt, "type">, resetSec
   return signed(encodeResetReceiptBody(f), "reset-sig", resetSecretKey);
 }
 
+export function encodeSuccessionBody(f: Omit<AccountSuccession, "type">): Uint8Array {
+  return new Writer()
+    .u8(WIRE_VERSION)
+    .u8(DocumentType.AccountSuccession)
+    .name(f.accountName)
+    .bytes(f.accountId)
+    .bytes(f.previousIdentityId)
+    .bytes(f.newIdentityId)
+    .u64(f.previousGeneration)
+    .u64(f.newGeneration)
+    .bytes(f.newCertificateHash)
+    .bytes(f.successionId)
+    .u64(f.issuedAt)
+    .bytes(f.authorityKeyId)
+    .finish();
+}
+
+/** Signed by an operational key the current reset-key list allows; the host signs it when it commits a succession. */
+export function buildSuccession(f: Omit<AccountSuccession, "type">, authoritySecretKey: Uint8Array): Uint8Array {
+  return signed(encodeSuccessionBody(f), "succession-sig", authoritySecretKey);
+}
+
 export function encodeResetKeyListBody(f: Omit<ResetKeyList, "type">): Uint8Array {
   const keys = [...f.keys].sort((a, b) => compareBytes(a.keyId, b.keyId));
   const w = new Writer().u8(WIRE_VERSION).u8(DocumentType.ResetKeyList).u64(f.version).u64(f.issuedAt).u64(f.expiresAt).u8(keys.length);

package/src/crypto.ts

@@ -40,6 +40,7 @@ export type Label =
   | "epoch-sig"
   | "record-sig"
   | "reset-sig"
+  | "succession-sig"
   | "reset-keys-sig"
   | "epoch-key"
   | "wrap"

package/src/errors.ts

@@ -31,6 +31,16 @@ export type ErrorCode =
   | "ROTATION_REQUIRED"
   | "COUNTER_EXHAUSTED"
   | "RECIPIENT_LIMIT"
+  /** A succession does not bind: certificate, identity, generation, account or previous state do not match (revision 9). */
+  | "SUCCESSION_BINDING"
+  /** A succession names a retired identity as previous or new; retirement is permanent. */
+  | "SUPERSEDED_IDENTITY"
+  /** Account recovery: the proposal has no valid authorization, or it expired, or a definitive conflict ended the proposal. */
+  | "AUTHORIZATION_REQUIRED"
+  | "AUTHORIZATION_EXPIRED"
+  | "REPLACEMENT_CONFLICT"
+  /** The outcome of a submitted succession is not yet known; retry or look it up. */
+  | "SUCCESSION_PENDING"
   // Delivery
   | "CLOCK_SKEW"
   | "EXPIRED"
@@ -51,7 +61,8 @@ const RETRYABLE: ReadonlySet<ErrorCode> = new Set<ErrorCode>([
   "ROTATION_REQUIRED",
   "LOCKED",
   "STORAGE_FAILURE",
-  "NETWORK"
+  "NETWORK",
+  "SUCCESSION_PENDING"
 ]);
 
 /**

package/src/identity.ts

@@ -32,7 +32,10 @@ import { KavachError } from "./errors.js";
 export interface AccountPin {
   readonly accountName: string;
   readonly accountKey: Uint8Array;
+  /** The identity of the current key: `H(C("identity") || name || AK)`. Changes at a succession. */
   readonly identityId: Uint8Array;
+  /** The account id: the identity at enrollment, what every document names. Constant across successions. */
+  readonly accountId: Uint8Array;
   readonly generation: bigint;
   readonly certificateHash: Uint8Array;
   readonly certificate: Uint8Array;
@@ -48,7 +51,7 @@ export type CertificateOutcome =
   | { readonly outcome: "ACCEPTED"; readonly pin: AccountPin; readonly rotate: boolean; readonly previous: AccountPin | undefined }
   | { readonly outcome: "DUPLICATE"; readonly pin: AccountPin };
 
-export function pinFromCertificate(doc: Parsed<AccountDevice>, previous?: AccountPin): AccountPin {
+export function pinFromCertificate(doc: Parsed<AccountDevice>, previous?: AccountPin, accountId?: Uint8Array): AccountPin {
   const iid = identityId(doc.accountName, doc.accountKey);
   const ids = previous ? [...previous.deviceIds] : [];
   if (!ids.some((d) => equalBytes(d, doc.deviceId))) ids.push(doc.deviceId);
@@ -56,6 +59,9 @@ export function pinFromCertificate(doc: Parsed<AccountDevice>, previous?: Accoun
     accountName: doc.accountName,
     accountKey: doc.accountKey,
     identityId: iid,
+    // The account id is carried from the previous pin (a succession keeps it) or given by the
+    // caller who resolved the chain; a first contact is its own root.
+    accountId: accountId ?? previous?.accountId ?? iid,
     generation: doc.generation,
     certificateHash: doc.bodyHash,
     certificate: concat(doc.body, doc.signature),
@@ -111,13 +117,17 @@ export interface OwnAccount {
   readonly accountName: string;
   readonly accountSeed: Uint8Array;
   readonly account: SigningKeypair;
+  /** The identity of this key. */
   readonly identityId: Uint8Array;
+  /** The account id: this identity for an account enrolled under this key, the root of the chain otherwise. */
+  readonly accountId: Uint8Array;
 }
 
-export function openAccount(accountName: string, accountSeed: Uint8Array): OwnAccount {
+export function openAccount(accountName: string, accountSeed: Uint8Array, accountId?: Uint8Array): OwnAccount {
   if (accountSeed.length !== SEED_BYTES) throw new KavachError("INVALID_KEY", "openAccount");
   const account = accountKeypair(accountSeed);
-  return { accountName, accountSeed, account, identityId: identityId(accountName, account.publicKey) };
+  const iid = identityId(accountName, account.publicKey);
+  return { accountName, accountSeed, account, identityId: iid, accountId: accountId ?? iid };
 }
 
 export function newAccountSeed(): Uint8Array {

package/src/index.ts

@@ -1,5 +1,5 @@
 /**
- * @plane31/blind-relay: Kavach v1 protocol (revision 6, wire version 5).
+ * @plane31/blind-relay: Kavach v1 protocol (revision 9, wire version 5).
  *
  * This entry is what an application imports: the client, its types, the errors and the few
  * helpers an app needs around it. Adapter and host authors import `@plane31/blind-relay/adapters`;
@@ -7,7 +7,7 @@
  * `@plane31/blind-relay/sodium`. Everything else is internal and reachable only by relative import.
  */
 export const PROTOCOL_NAME = "Kavach";
-export const PROTOCOL_REVISION = 8;
+export const PROTOCOL_REVISION = 9;
 
 // The client ---------------------------------------------------------------------------------------
 export {
@@ -23,10 +23,12 @@ export {
   type HistoryPage,
   type HistoryQuery,
   type Inspection,
+  type KeyChangeEntry,
   type Newest,
   type OpenOptions,
   type PauseReason,
   type ReceiveResult,
+  type ReplacementProposal,
   type SyncError,
   type SyncOptions,
   type SyncReport
@@ -39,7 +41,7 @@ export { KavachError, isKavachError, type ErrorCode } from "./errors.js";
 export type { RecordKind } from "./codec.js";
 
 // Configuration ------------------------------------------------------------------------------------
-export { validatePolicy, type KindDeclaration, type RetentionPolicy } from "./policy.js";
+export { validatePolicy, type KindDeclaration, type ReplacementModel, type RetentionPolicy } from "./policy.js";
 export type { ResetTrustConfig } from "./reset.js";
 export { setCryptoBackend, type CryptoBackend } from "./crypto.js";
 

package/src/policy.ts

@@ -21,8 +21,18 @@ export interface KindDeclaration {
   readonly headerClass: 0 | 1 | 2 | 3;
 }
 
+/**
+ * Which replacement models the product enables (protocol section 4, revision 9): `continuity`,
+ * the device holds the account key, recovered through the platform or a code, and the host can
+ * never rebind a key; `recovery`, the host's authority signs a succession to fresh keys after
+ * the product's fresh authentication; or `both`. A property of the app build, enforced by every
+ * verifying peer: a client without `recovery` rejects every succession document.
+ */
+export type ReplacementModel = "continuity" | "recovery" | "both";
+
 export interface RetentionPolicy {
   readonly version: number;
+  readonly replacement: ReplacementModel;
   readonly deliveryWindowMs: bigint;
   readonly appendRetryWindowMs: bigint;
   readonly hygieneRotationMs: bigint;
@@ -34,7 +44,7 @@ export interface RetentionPolicy {
 /** The largest kind the envelope carries. */
 export const MAX_WIRE_KIND = 255;
 
-const FIELDS: readonly (keyof RetentionPolicy)[] = ["version", "deliveryWindowMs", "appendRetryWindowMs", "hygieneRotationMs", "maxOutboxRecords", "maxOutboxBytes", "kinds"];
+const FIELDS: readonly (keyof RetentionPolicy)[] = ["version", "replacement", "deliveryWindowMs", "appendRetryWindowMs", "hygieneRotationMs", "maxOutboxRecords", "maxOutboxBytes", "kinds"];
 
 /** A missing or malformed policy is rejected; the SDK never substitutes defaults. */
 export function validatePolicy(policy: unknown): RetentionPolicy {
@@ -66,8 +76,10 @@ export function validatePolicy(policy: unknown): RetentionPolicy {
     if (headerClass !== 0 && headerClass !== 1 && headerClass !== 2 && headerClass !== 3) throw new KavachError("MALFORMED", stage, `kinds[${i}].headerClass must be 0 to 3`);
     return { kind, retentionMs: big(`kinds[${i}].retentionMs`, k.retentionMs), queue: k.queue, history: k.history, newest: k.newest, headerClass };
   });
+  if (p.replacement !== "continuity" && p.replacement !== "recovery" && p.replacement !== "both") throw new KavachError("MALFORMED", stage, "replacement must be continuity, recovery or both");
   return {
     version: int("version", p.version),
+    replacement: p.replacement,
     deliveryWindowMs: big("deliveryWindowMs", p.deliveryWindowMs),
     appendRetryWindowMs: big("appendRetryWindowMs", p.appendRetryWindowMs),
     hygieneRotationMs: big("hygieneRotationMs", p.hygieneRotationMs),
@@ -86,3 +98,13 @@ export function kindOf(policy: RetentionPolicy, kind: number): KindDeclaration |
 export function historyKinds(policy: RetentionPolicy): readonly number[] {
   return policy.kinds.filter((k) => k.history).map((k) => k.kind);
 }
+
+/** Whether a deployment accepts successions at all; a peer without it rejects every type 9 document. */
+export function acceptsSuccession(policy: RetentionPolicy): boolean {
+  return policy.replacement !== "continuity";
+}
+
+/** Whether a device may replace itself by holding the account key (restoreAccount). */
+export function allowsContinuity(policy: RetentionPolicy): boolean {
+  return policy.replacement !== "recovery";
+}

package/src/rows.ts

@@ -14,6 +14,7 @@ export function pinToRow(p: AccountPin): PinRow {
     accountName: p.accountName,
     accountKey: toHex(p.accountKey),
     identityId: toHex(p.identityId),
+    accountId: toHex(p.accountId),
     generation: big(p.generation),
     certificateHash: toHex(p.certificateHash),
     certificate: toHex(p.certificate),
@@ -30,6 +31,7 @@ export function rowToPin(r: PinRow): AccountPin {
     accountName: r.accountName,
     accountKey: fromHex(r.accountKey),
     identityId: fromHex(r.identityId),
+    accountId: fromHex(r.accountId ?? r.identityId),
     generation: unbig(r.generation),
     certificateHash: fromHex(r.certificateHash),
     certificate: fromHex(r.certificate),

package/src/store.ts

@@ -17,7 +17,7 @@ export interface SecretStore {
   delete(name: SecretName): Promise<void>;
 }
 
-export type SecretName = "accountSeed" | "deviceSeed" | "recoveryKey" | "storageKey" | "instanceId" | "pendingReset";
+export type SecretName = "accountSeed" | "deviceSeed" | "recoveryKey" | "storageKey" | "instanceId" | "pendingReset" | "pendingReplacement";
 
 // Logical tables. Rows are JSON-safe: bytes as hex strings, u64 as decimal strings.
 
@@ -29,11 +29,15 @@ export interface MetaRow {
   historyIndex?: 1;
   /** Set once the newest slots are built from history; a store from before the slot table is rebuilt on open. */
   newest?: 1;
+  /** The account id (revision 9): the identity at enrollment, constant across successions. Absent on a store from before revision 9, where it equals `identityId`. */
+  accountId?: string;
   instanceId: string;
   accountName: string;
   identityId: string;
   certificateHash: string;
   state: StoreState;
+  /** Set by account recovery: discovery of this account's circles through the host, page by page, until complete; failed circles wait in `retry`. */
+  bootstrap?: { cursor?: string; complete: boolean; retry?: BootstrapRetryRow[]; pagesDone?: boolean };
 }
 
 export interface SelfRow {
@@ -47,7 +51,10 @@ export interface SelfRow {
 export interface PinRow {
   accountName: string;
   accountKey: string;
+  /** The account's current identity (revision 9); before it, the one identity an account ever had. */
   identityId: string;
+  /** The account id: the identity at enrollment. Absent on a row from before revision 9, where it is `identityId`. */
+  accountId?: string;
   generation: string;
   certificateHash: string;
   certificate: string;
@@ -244,8 +251,9 @@ export interface PendingResetRow {
   resetId: string;
   oldIdentityId: string;
   certificate: string;
-  vault: string;
-  vaultHash: string;
+  /** Absent on a recovery-only profile without a provider: no vault. */
+  vault: string | undefined;
+  vaultHash: string | undefined;
 }
 
 /**
@@ -265,6 +273,99 @@ export interface EnqueueKeyRow {
   sentAt: string;
 }
 
+/** One accepted succession transition, keyed `<accountId>:<previousGeneration padded to 20>`; the wire is the latest attestation seen. */
+export interface SuccessionRow {
+  accountId: string;
+  accountName: string;
+  successionId: string;
+  previousIdentityId: string;
+  newIdentityId: string;
+  previousGeneration: string;
+  newGeneration: string;
+  newCertificateHash: string;
+  authorityKeyId: string;
+  wire: string;
+  acceptedAt: string;
+}
+
+/** Every identity an account has had, keyed by identity id: which account it belongs to and whether it is retired. */
+export interface IdentityRow {
+  accountId: string;
+  accountName: string;
+  /** The account key of this identity, so a snapshot signed under a retired owner key still verifies. Absent for a chain root whose certificate this device never saw. */
+  accountKey?: string;
+  /** The generation at which this identity became current (1 for a root). */
+  sinceGeneration: string;
+  /** Retired as a key identity, by a succession or a reset. The account itself may live on under a successor. */
+  retired: boolean;
+  /** On the root row only: the account was reset at this time; no member of the chain is a recipient any more. */
+  resetAt?: string;
+}
+
+/** The durable key-change notice, written in the transaction that accepts a succession or a reset; keyed `<acceptedAt padded>:<accountId>`. */
+export interface KeyChangeRow {
+  accountId: string;
+  accountName: string;
+  previousIdentityId: string;
+  newIdentityId: string;
+  generation: string;
+  reason: "succession" | "reset";
+  successionId: string | undefined;
+  acceptedAt: string;
+}
+
+/** T11: a replacement proposal prepared on a fresh device, kept until it commits or is definitively conflicted. */
+export interface ReplacementRow {
+  successionId: string;
+  accountName: string;
+  accountId: string;
+  expectedCertificateHash: string;
+  expectedGeneration: string;
+  /** The exact certificate bytes under the new key, at expectedGeneration + 1. */
+  certificate: string;
+  /** The fresh vault at revision 1 the succession installs, so a retry sends identical bytes; absent without a provider. */
+  vault: string | undefined;
+  vaultHash: string | undefined;
+  deviceId: string;
+  /** Set by a definitive conflict: the proposal can never commit and the next prepare replaces it. */
+  stale: boolean;
+  conflictGeneration: string | undefined;
+}
+
+/** A circle's sharing preference as the host holds it, with the ordering that makes the latest user action win. */
+export interface PreferenceRow {
+  circleId: string;
+  enabled: boolean;
+  /** The host's revision the device last confirmed; 0 before any confirmation. */
+  revision: string;
+  /** A change the host has not confirmed, with the local sequence it carries; cleared only by the response to that sequence. */
+  pending: { enabled: boolean; sequence: string } | undefined;
+  /** The next local sequence to assign. */
+  nextSequence: string;
+}
+
+/** Paged chain retrieval in progress for an account: verified pages persist, the pin moves only when complete. */
+export interface ChainProgressRow {
+  accountId: string;
+  /** The identity the verified prefix starts from (the pinned identity, or the account id at first contact). */
+  startIdentityId: string;
+  /** The links verified so far, in order; the pin has not moved for any of them. */
+  links: { wire: string; certificate: string }[];
+  /** The generation to continue from. */
+  nextGeneration: string;
+  complete: boolean;
+}
+
+/** One circle the host listed during bootstrap that this device could not adopt yet; retried by every sync until it lands. */
+export interface BootstrapRetryRow {
+  circleId: string;
+  ownerAccountId: string;
+  role: "owner" | "member" | "pending";
+  snapshot: string | undefined;
+  enabled: boolean | undefined;
+  preferenceRevision: string;
+}
+
 export interface Tables {
   meta: MetaRow;
   self: SelfRow;
@@ -290,6 +391,12 @@ export interface Tables {
   retiredIdentities: { identityId: string };
   clock: ClockRow;
   pendingReset: PendingResetRow;
+  successions: SuccessionRow;
+  identities: IdentityRow;
+  keyChanges: KeyChangeRow;
+  replacement: ReplacementRow;
+  preferences: PreferenceRow;
+  chainProgress: ChainProgressRow;
 }
 
 export type TableName = keyof Tables;