@kokuin/controller 0.1.0 → 0.2.0

package/lib/events.d.ts

@@ -1,6 +1,13 @@
-import type { DIDString, ResolvedSigningKey } from '@kokuin/token';
+import type { DIDString } from '@kokuin/token';
+import type { EpochEventCommon } from './epoch-events.js';
 export declare const DID_PREFIX = "did:kokuin:";
-export type EventType = 'icp' | 'rot' | 'rev';
+/**
+ * The root chain's event types, and only those: it holds the key-establishing events. Management
+ * actions — member adds, renewals, removals and revokes — live in the epoch a chain event opens,
+ * never on the chain. A chain entry of any other `t`, a `rev` from an older log included, takes the
+ * fold's unknown-type path, so a critical one fails the fold closed.
+ */
+export type EventType = 'icp' | 'rot';
 export type EventCommon = {
     /** Inception format version. Absent must never be inferred; always written. */
     v: 1;
@@ -41,7 +48,11 @@ export type InceptionEvent = EventCommon & {
      */
     r: string;
 };
-export type SignedEvent<E extends EventCommon = EventCommon> = {
+/**
+ * Generic over both tiers: a root-chain event and an epoch event share the envelope and signatures
+ * over canonical bytes, and nothing else.
+ */
+export type SignedEvent<E extends EventCommon | EpochEventCommon = EventCommon> = {
     event: E;
     /** base64url ed25519 signatures over the canonical event bytes, positional against `event.k`. */
     sigs: Array<string>;
@@ -51,7 +62,14 @@ export type SignedEvent<E extends EventCommon = EventCommon> = {
      */
     recoveryKey?: string;
 };
-export declare function signEvent(event: EventCommon, privateKeys: Array<Uint8Array>): Array<string>;
+export declare function signEvent(event: EventCommon | EpochEventCommon, privateKeys: Array<Uint8Array>): Array<string>;
+/**
+ * A published key list: an array of strings. `k`, `n`, `ka` and the deny snapshot are carried into
+ * the folded state, so a bad shape must be rejected where it is published, not one event away where
+ * it is next read (a non-array `n` would throw in the *next* rotate; a non-array `k` is a `KeyState`
+ * whose type lies).
+ */
+export declare function isKeyList(value: unknown): value is Array<string>;
 /**
  * Total: a malformed signature or key yields false rather than throwing, including a body the
  * canonicalizer refuses. `canonicalBytes` throws on a non-finite number or nesting past
@@ -60,17 +78,7 @@ export declare function signEvent(event: EventCommon, privateKeys: Array<Uint8Ar
  * total and a direct caller reaches it with a parsed body. `false` is honest: a body with no
  * canonical encoding has no bytes for a signature to be over.
  */
-export declare function verifySignatures(event: EventCommon, sigs: Array<string>, keys: Array<string>): boolean;
-/**
- * Whether one of an event's signatures was made by `key` — the counterpart of
- * {@link verifySignatures} for a signer the *event* does not name (resolved from a DID elsewhere). A
- * capability-authorised revoke needs exactly this: its author is the capability's `aud`, which the
- * fold cannot resolve, so it is handed the key and checks the signature itself.
- *
- * Total, EdDSA only — all {@link signEvent} produces. An ES256 audience therefore cannot author a
- * revoke, which fails closed until events grow a second signature algorithm.
- */
-export declare function verifyEventSignedBy(signed: SignedEvent, key: ResolvedSigningKey): boolean;
+export declare function verifySignatures(event: EventCommon | EpochEventCommon, sigs: Array<string>, keys: Array<string>): boolean;
 /**
  * Deterministic inception. Only seed-derived, canonical material — no timestamp, nonce, or label —
  * so the DID is a pure function of the seed and profile index. Never add a label: a mistyped one on
@@ -81,6 +89,36 @@ export declare function didFromInception(event: InceptionEvent): DIDString;
 /** The did:kokuin: identifier a seed and profile produce, without signing an inception. */
 export declare function didFor(seed: Uint8Array, profile: number): DIDString;
 export declare function verifyInception(signed: SignedEvent<InceptionEvent>, did: string): boolean;
+/**
+ * One management member as a snapshot carries it: the DID it acts as, the Ed25519 key that DID is
+ * pinned to (in the spelling `k` uses), the digest of the `add` that admitted it — its incarnation,
+ * which renewals and removals name — and its lease end in unix seconds.
+ *
+ * The fold never reads `lease` against a clock: it bounds the grants the member mints, nothing on the
+ * log. Only a removal ends a member's log authority.
+ */
+export type MemberEntry = {
+    did: string;
+    key: string;
+    add: string;
+    lease: number;
+};
+/**
+ * The whole management state a root-chain event leaves behind: the member set and the deny set. The
+ * state after the event **is** this snapshot — nothing before it contributes — so it is root's
+ * chosen replacement state, not a proven merge of everything that happened before it.
+ */
+export type StateSnapshot = {
+    members: Array<MemberEntry>;
+    deny: Array<string>;
+};
+/**
+ * The shape of one snapshot member, nothing more: whether the DID carries the key, whether the key
+ * is Ed25519, and whether it collides with a root key are rules over the whole snapshot and its chain,
+ * checked by the fold. `lease` must be a non-negative safe integer — unix seconds — because grants
+ * compare `exp` against it, and a fraction, a negative or an unsafe integer has no single reading.
+ */
+export declare function isMemberEntry(value: unknown): value is MemberEntry;
 export type RotateEvent = EventCommon & {
     t: 'rot';
     /** Keys the prior event pre-committed, now revealed, multicodec-tagged and multibase-encoded. */
@@ -100,57 +138,47 @@ export type RotateEvent = EventCommon & {
      * {@link isPublishedRotate}). Not surfaced in `KeyState`: it belongs to a position, not the keys.
      */
     a?: string;
-    /** Deny-set snapshot. Replaces the accumulated set, pruning it. */
-    d?: Array<string>;
-};
-export type CreateRotateOptions = {
-    seal?: string;
     /**
-     * The complete deny set this rotate leaves behind — **a replacement, not an addition**. `d` present
-     * replaces the accumulated set, `d` absent carries it forward. A caller writing one entry meaning
-     * "also deny this" silently drops every accumulated entry — un-revoking devices and un-retiring
-     * leaked keys — with no error and nothing in the log saying anything was lost. Build it from the
-     * folded state with {@link pruneDenySet}. `[]` is the deliberate "clear everything" a cold rotate
-     * does to recover from a bad management tier. A rotate cannot establish a key its own snapshot
-     * denies; the fold refuses such an event.
+     * Member half of the state snapshot — see {@link StateSnapshot}. Required, with `d`, on every
+     * rotate that is not a reset: every rotate is a settlement. A reset carries both or neither.
      */
-    denySnapshot?: Array<string>;
-    /**
-     * Where the currently-active authority key lives — the position of the last `icp`/`rot`, i.e. the
-     * fold's `keyGen`/`keySeq`.
-     *
-     * Defaults to `prior`'s position, right only while sequence and derivation index still coincide: a
-     * `rev` advances `s` and establishes no key, so after the first revoke of a generation the two part
-     * company **and never rejoin**. Every rotate after a revoke needs this, not just the one directly
-     * on it. Optional rather than required because {@link createRotate} verifies the key it reveals
-     * against `prior`'s commitment and throws on disagreement — provably right where omitted, an error
-     * (not an unfoldable event) where not. Take it from `KeyState.keyGen`/`keySeq`.
-     */
-    keyPosition?: {
-        gen: number;
-        seq: number;
-    };
+    m?: Array<MemberEntry>;
+    /** Deny half of the state snapshot. Replaces the set the prior state held outright. */
+    d?: Array<string>;
 };
 export type CreateRotateParams = {
     seed: Uint8Array;
     profile: number;
     did: string;
     prior: EventCommon;
-    options?: CreateRotateOptions;
+    /**
+     * The complete state this rotate leaves behind — **a replacement, not an addition**. The state
+     * after a rotate is its snapshot and nothing before it, so a caller writing one deny entry meaning
+     * "also deny this" silently drops every other entry and every member — un-revoking devices and
+     * dismissing the management tier — with nothing in the log saying anything was lost. Build it from
+     * the folded state with {@link snapshotOf}, which also carries every member forward.
+     *
+     * Required: there is no "carry the prior state forward" rotate, because the prior state may hold
+     * epoch effects a verifier holding only the chain cannot reproduce. Two rules the fold enforces
+     * here: a member may not pin a key on, or committed by, this generation's root chain; and a
+     * retired-key denial an earlier rotate in the generation carried may not be dropped.
+     */
+    snapshot: StateSnapshot;
+    /** Seal: an anchored external digest — see {@link RotateEvent.a}. */
+    seal?: string;
 };
 /**
  * A rotate reveals the keys the prior event pre-committed and commits the next set, signed by the
  * newly revealed keys (per KERI — what makes a stolen current key unable to rotate). Reproducible
- * from the seed alone unless it carries a seal or deny snapshot.
+ * from the seed and the snapshot unless it carries a seal.
+ *
+ * The root chain holds only key-establishing events, so a rotate's sequence and its derivation index
+ * are the same number: the key it reveals sits one past `prior`'s position.
  *
  * **Throws rather than emitting an event the fold will reject.** The revealed key must be the one
- * `prior` committed in `n`, and `options.keyPosition` decides which key gets derived — so a wrong
- * position used to produce a well-formed, signed event no fold would accept. The two are checked
- * against each other here. When `prior` carries no commitment (a `rev`), `keyPosition` is required:
- * the default would derive a key one past the *revoke*, which nothing committed, and this is the one
- * case unverifiable from `prior` alone.
+ * `prior` committed in `n`, which a prior not built from this chain's own events need not be.
  */
-export declare function createRotate({ seed, profile, did, prior, options, }: CreateRotateParams): SignedEvent<RotateEvent>;
+export declare function createRotate({ seed, profile, did, prior, snapshot, seal, }: CreateRotateParams): SignedEvent<RotateEvent>;
 /**
  * A rotate is valid when it chains to the prior digest, its revealed keys match the prior event's
  * pre-rotation commitment, and its signatures verify against those keys.
@@ -165,15 +193,25 @@ export declare function verifyRotate(signed: SignedEvent<RotateEvent>, prior: {
  *
  * Anchored to the inception, not the log head: the recovery key lives on the root-retained
  * derivation branch and its digest is committed in the deterministic inception, so a restored
- * mnemonic can author one with no log knowledge or availability. Carries no options — no seal, `d`
- * always `[]` — so a reset is a pure function of `(seed, profile, gen)`, and two blind resets at one
- * generation produce identical bytes that resolve as idempotent re-derivation, not duplicity.
+ * mnemonic can author one with no log knowledge or availability.
+ *
+ * **Blind** (no `snapshot`): no seal, `d: []` and no `m`, so a blind reset is a pure function of
+ * `(seed, profile, gen)` and two blind resets at one generation produce identical bytes that resolve
+ * as idempotent re-derivation, not duplicity. The new epoch starts empty and root re-adds members.
+ * This is the path for a root that does not know the log's state.
+ *
+ * **With a snapshot**: the same reset carries the member and deny sets, so one recovery-key
+ * signature is the whole recovery. Two resets at one generation with different bytes are then
+ * duplicity — which only the recovery-key holder can cause, and a reset at a higher generation
+ * resolves. Members keep their `add` references, but every grant names its generation, so every
+ * grant minted under the prior one still dies. The snapshot is checked against the **new**
+ * generation's keys, and no retired-key denial of the old one need carry over.
  *
  * The root need not know the current generation, only eventually exceed it (no attacker can author a
  * competing reset at any generation): a blind root starts at `gen = 1` and retries higher if it
  * learns of one — the cost is a round trip, never loss of control.
  */
-export declare function createReset(seed: Uint8Array, profile: number, gen: number): SignedEvent<RotateEvent>;
+export declare function createReset(seed: Uint8Array, profile: number, gen: number, snapshot?: StateSnapshot): SignedEvent<RotateEvent>;
 /**
  * A reset verifies against the committed recovery digest, not the pre-rotation set. Both values it
  * needs — the anchor digest and the recovery commitment — come from the inception, the *only* place
@@ -185,102 +223,18 @@ export declare function createReset(seed: Uint8Array, profile: number, gen: numb
  */
 export declare function verifyReset(signed: SignedEvent<RotateEvent>, inception: InceptionEvent): boolean;
 /**
- * How a `rev` target names a **key** rather than a DID: `#<the multibase key exactly as it appears in
+ * How a deny entry names a **key** rather than a DID: `#<the multibase key exactly as it appears in
  * `k`>`, the same spelling a token's `kid` uses. One spelling for one thing — unambiguous against
  * `did:…` on sight, so a bare multibase string is not a second accepted encoding, any more than for
  * `kid`.
  */
 export declare const KEY_TARGET_PREFIX = "#";
-/** The deny-set spelling of `key` — what {@link createRevoke} takes as its target to deny it. */
+/** The deny-set spelling of `key` — what a snapshot's `d` carries to deny it. */
 export declare function keyTarget(key: string): string;
 /**
- * The key a `rev` target names, or `null` when it names a DID instead. Total on any string: a target
- * of neither form lands in the deny set as the opaque identifier it is. The body is not validated
+ * The key a deny entry names, or `null` when it names a DID instead. Total on any string: an entry of
+ * neither form lands in the deny set as the opaque identifier it is. The body is not validated
  * against multibase — a `#` naming nothing denies nothing, exactly as a `did:` naming nobody does,
  * and rejecting it would only add a way for a well-formed log to stop folding.
  */
 export declare function keyFromTarget(target: string): string | null;
-export type RevokeEvent = EventCommon & {
-    t: 'rev';
-    /**
-     * What to deny, in one of two spellings, never a capability `jti`.
-     *
-     * A **DID** (`did:…`) denies a holder: no capability whose `aud` is that DID is valid from this
-     * position onward — one entry covers a device's life. A **key** ({@link keyTarget}) denies a
-     * signer: nothing this profile signed with that key verifies from this position onward, and it
-     * names a key of *this* profile (the deny set is the subject's own).
-     *
-     * One field carries both because they are enforced at opposite ends of the same set: the DID form
-     * by `@kokuin/capability` against a capability's `aud`, the key form by the resolver against the
-     * key a `kid` selects. Neither spelling can be mistaken for the other.
-     */
-    x: string;
-    /** A serialized capability authorising a non-authority signer. Verified in the fold. */
-    cap?: string;
-};
-export type CreateRevokeParams = {
-    seed: Uint8Array;
-    profile: number;
-    did: string;
-    prior: EventCommon;
-    target: string;
-    keyPosition: {
-        gen: number;
-        seq: number;
-    };
-    /** A serialized capability authorising this signer, when the signer is not an authority key. */
-    cap?: string;
-};
-/**
- * Revoke a DID or a key — see {@link RevokeEvent.x} for the two spellings.
- *
- * Naming the device DID rather than a `jti` makes this one entry per device for its life — covering
- * capabilities the verifier has never seen and future re-mints, where per-`jti` revocation would grow
- * with every renewal. A key target retires a leaked key for material it *already* signed: `rotate`
- * only retires it for new issuance (`resolve` is head-only), but already-issued material verifies
- * through `resolveHistoric`, which survives a rotate by design, so a thief holding a rotated-away key
- * could still mint one that verified. Retirement is therefore explicit, keeping the promise that a
- * routine rotate does not invalidate already-issued material intact.
- *
- * **A key the profile currently publishes cannot be denied** — the fold rejects it (see the `rev`
- * branch of `stepEvent`). Rotate first, then deny the key the rotate retired.
- *
- * `prior` answers "next sequence, what to chain to"; `keyPosition` separately answers "where the
- * active authority key lives". They coincide only for an `icp`/`rot` prior — a `rev` establishes no
- * key, so a revoke on a revoke still points at the last `icp`/`rot` position.
- */
-export declare function createRevoke({ seed, profile, did, prior, target, keyPosition, cap, }: CreateRevokeParams): SignedEvent<RevokeEvent>;
-export type CreateRevokeOptions = {
-    /** A serialized capability authorising this signer, when the signer is not an authority key. */
-    cap?: string;
-};
-export type CreateRevokeWithKeyParams = {
-    privateKey: Uint8Array;
-    did: string;
-    prior: EventCommon;
-    target: string;
-    /** A serialized capability authorising this signer, when the signer is not an authority key. */
-    cap?: string;
-};
-/**
- * Revoke a DID, signing with an Ed25519 key the caller already holds rather than deriving one from
- * the profile seed.
- *
- * The builder for the actor a capability-authorised revoke exists for: a device holding a management
- * capability, which by design never receives the profile sub-seed. `createRevoke` can only sign as
- * the profile itself, so without this the feature had no API but re-implementing the signing
- * convention per consumer — the duplication `createControllerCapabilityVerifier` prevents on the
- * verifying side.
- *
- * The key is the audience key the capability pins in `cnf`, and the fold checks the event's signature
- * against exactly that, so the two must match. Ed25519 only. Takes the private key rather than an
- * identity because no identity type here signs raw bytes — a `KeyStore` entry hands back exactly this
- * shape. Byte-identical to {@link createRevoke} given the same key; no `keyPosition`, which exists
- * only to derive a key from a seed.
- */
-export declare function createRevokeWithKey({ privateKey, did, prior, target, cap, }: CreateRevokeWithKeyParams): SignedEvent<RevokeEvent>;
-/** Authority-signed revoke. Capability-authorised revokes are checked in the fold. */
-export declare function verifyRevoke(signed: SignedEvent<RevokeEvent>, prior: {
-    digest: string;
-    keys: Array<string>;
-}): boolean;