@kokuin/controller 0.1.0 → 0.2.0

package/lib/epoch-events.d.ts

@@ -0,0 +1,139 @@
+import { type SignedEvent } from './events.js';
+import type { KeyState } from './fold.js';
+export type EpochEventType = 'add' | 'ren' | 'rmv' | 'rev';
+export type EpochEventCommon = {
+    /** Format version. Always written, never inferred. */
+    v: 1;
+    t: EpochEventType;
+    /** Profile DID. */
+    i: string;
+    /** Generation of the root chain this event's epoch belongs to. */
+    g: number;
+    /**
+     * Digest of the root-chain event that opened the epoch. An event naming any other epoch has no
+     * effect: its effect is either in the newer snapshot or was dropped by it.
+     */
+    e: string;
+    /**
+     * Parents: `e` itself or digests of events of the same epoch -- every head the author knows, a
+     * recommendation the fold cannot enforce. 1 to {@link MAX_EVENT_PARENTS} entries, no duplicates. A
+     * list, not a single predecessor, because concurrent members branch and a later event joins them.
+     */
+    p: Array<string>;
+    /**
+     * Criticality, in the envelope for the same reason as on the root chain. Always `true` here, so a
+     * verifier predating the management tier fails closed rather than skipping a revoke.
+     */
+    crit: boolean;
+    /**
+     * The signing member's add digest -- its incarnation, not its DID, so a removed and re-added member
+     * signs under a different reference. Absent means root: n-of-n over the chain head's `k`.
+     */
+    by?: string;
+};
+/** Root-only: a member is admitted only by a root signature. */
+export type AddEvent = EpochEventCommon & {
+    t: 'add';
+    /** The member's DID: an Ed25519 `did:key`, or a long-form `did:peer:4` carrying `key`. */
+    did: string;
+    /** The pinned Ed25519 key, encoded as a key in `k` is. Everything the member signs verifies under it. */
+    key: string;
+    /** Lease end, unix seconds. Bounds the member's grants; the fold never reads it. */
+    lease: number;
+};
+export type RenewEvent = EpochEventCommon & {
+    t: 'ren';
+    /** The incarnation renewed, by add digest, so a delayed renew never carries over to a re-add. */
+    add: string;
+    /** New lease end, unix seconds. Merges as the maximum per incarnation. */
+    lease: number;
+};
+export type RemoveEvent = EpochEventCommon & {
+    t: 'rmv';
+    /** The incarnation removed, by add digest. Dominates any renewal of it. */
+    add: string;
+};
+export type RevokeEvent = EpochEventCommon & {
+    t: 'rev';
+    /** A DID or a key target, the two spellings the root chain's deny set takes -- see `keyTarget`. */
+    x: string;
+};
+export type EpochEvent = AddEvent | RenewEvent | RemoveEvent | RevokeEvent;
+export type EpochSigner = {
+    root: {
+        seed: Uint8Array;
+        profile: number;
+    };
+} | {
+    member: {
+        privateKey: Uint8Array;
+        add: string;
+    };
+};
+type BuildBase = {
+    did: string;
+    head: KeyState;
+    parents: Array<string>;
+};
+export type CreateAddParams = BuildBase & {
+    seed: Uint8Array;
+    profile: number;
+    member: {
+        did: string;
+        key: string;
+        lease: number;
+    };
+};
+export type CreateRenewParams = BuildBase & {
+    signer: EpochSigner;
+    add: string;
+    lease: number;
+};
+export type CreateRemoveParams = BuildBase & {
+    signer: EpochSigner;
+    add: string;
+};
+export type CreateRevokeParams = BuildBase & {
+    signer: EpochSigner;
+    target: string;
+};
+/** Admit a member. Root-only by type: there is no member signer for an add. */
+export declare function createAdd({ seed, profile, member, ...base }: CreateAddParams): SignedEvent<AddEvent>;
+/** Extend an incarnation's lease. A member may renew another member, never itself. */
+export declare function createRenew({ signer, add, lease, ...base }: CreateRenewParams): SignedEvent<RenewEvent>;
+/** End an incarnation's log authority. A member may remove another member, never itself. */
+export declare function createRemove({ signer, add, ...base }: CreateRemoveParams): SignedEvent<RemoveEvent>;
+/**
+ * Deny an edge holder or a retired key. Root or any single member; a member may not target a member
+ * of its causal past, which removal covers instead.
+ */
+export declare function createRevoke({ signer, target, ...base }: CreateRevokeParams): SignedEvent<RevokeEvent>;
+/**
+ * Whether `value` has the shape of a signed epoch event: the envelope, the fields its type carries,
+ * the parent rules, and a canonical body within {@link MAX_EVENT_BYTES}. Total on anything
+ * `JSON.parse` yields, since an epoch event arrives from a peer or an untrusted store. A request-limit
+ * check: failing it rejects input and changes no state.
+ *
+ * Structure only. It says nothing about who signed, whether the signer may, or whether the parents
+ * exist -- those belong to {@link verifyEpochSignature} and the fold. `crit` must be exactly `true`:
+ * every type here is critical, and a known type declaring otherwise is a body whose envelope
+ * contradicts it. A `recoveryKey` on the envelope is refused rather than ignored -- only a reset
+ * reveals one, and a member nothing reads is a field that lies.
+ */
+export declare function isEpochEventShape(value: unknown): value is SignedEvent<EpochEvent>;
+/**
+ * Whether `signed` verifies under the signer the caller names. The fold names it from `by`: absent,
+ * the chain head's keys; present, the key the referenced add pinned.
+ *
+ * The signer kind must agree with `by`, so a root-signed body cannot pass as a member's or the
+ * reverse: a single-key root and a member are otherwise the same check, and an event whose `by` the
+ * caller did not consult would be authorised as whoever happened to be asked about. Root is n-of-n
+ * over `rootKeys` (via `verifySignatures`); a member signs alone, so exactly one signature, under the
+ * pinned key. Total: a malformed body or signature is `false`.
+ */
+export declare function verifyEpochSignature(signed: SignedEvent<EpochEvent>, signer: {
+    rootKeys: Array<string>;
+} | {
+    memberKey: string;
+}): boolean;
+export {};

package/lib/epoch-events.js

@@ -0,0 +1,177 @@
+import { canonicalBytes, isCanonicalizable } from './canonical.js';
+import { authorityPath, deriveKeyPair } from './derivation.js';
+import { didFor, signEvent, verifySignatures } from './events.js';
+import { encodeKey } from './keys.js';
+import { MAX_EVENT_BYTES, MAX_EVENT_PARENTS, MAX_EVENT_SIGNATURES } from './limits.js';
+const EPOCH_EVENT_TYPES = new Set([
+    'add',
+    'ren',
+    'rmv',
+    'rev'
+]);
+/**
+ * Sign `fields` as an event of `head`'s epoch.
+ *
+ * **Throws rather than emitting an event the fold will reject**, the rule the root-chain builders
+ * follow: an empty or oversized parent list, a fractional lease, or a body past the byte limit is
+ * refused here, where the caller can still act. So is a root signer whose derived key `head` does
+ * not publish, when the seed is this DID's root -- a stale `keyGen`/`keySeq` would otherwise produce
+ * a well-formed, signed event no fold accepts. A foreign seed is left alone, as `createRotate` leaves
+ * it: a mismatch there says nothing, and the fold is the layer that rejects it.
+ */ function buildEvent(t, signer, { did, head, parents }, fields) {
+    if (parents.length === 0) {
+        throw new Error('Epoch event: at least one parent is required -- the epoch digest at minimum');
+    }
+    // Code-unit order, so the written list is a function of the set alone.
+    const p = [
+        ...new Set(parents)
+    ].sort();
+    let privateKey;
+    if ('root' in signer) {
+        const { seed, profile } = signer.root;
+        const pair = deriveKeyPair(seed, authorityPath(profile, head.keyGen, head.keySeq), 'EdDSA');
+        const derived = encodeKey(pair.publicKey, 'EdDSA');
+        // Exactly the one key: the verifier checks n-of-n, and this generator signs with one.
+        if (didFor(seed, profile) === did && !(head.keys.length === 1 && head.keys[0] === derived)) {
+            throw new Error(`Epoch event: the key at (gen ${head.keyGen}, seq ${head.keySeq}) is not the head's only ` + 'published key -- pass the folded head, whose keyGen / keySeq name the active authority key');
+        }
+        privateKey = pair.privateKey;
+    } else {
+        privateKey = signer.member.privateKey;
+    }
+    const common = {
+        v: 1,
+        t,
+        i: did,
+        g: head.gen,
+        e: head.epoch,
+        p,
+        crit: true
+    };
+    // Conditionally spread: a root event has no `by` key at all, not one set to undefined.
+    const event = {
+        ...common,
+        ...'member' in signer ? {
+            by: signer.member.add
+        } : {},
+        ...fields
+    };
+    const signed = {
+        event,
+        sigs: signEvent(event, [
+            privateKey
+        ])
+    };
+    if (!isEpochEventShape(signed)) {
+        throw new Error(`Epoch event: the ${t} built is not a well-formed epoch event -- check the parent count ` + `(at most ${MAX_EVENT_PARENTS} distinct), integer leases and the ${MAX_EVENT_BYTES}-byte body limit`);
+    }
+    return signed;
+}
+/** Admit a member. Root-only by type: there is no member signer for an add. */ export function createAdd({ seed, profile, member, ...base }) {
+    return buildEvent('add', {
+        root: {
+            seed,
+            profile
+        }
+    }, base, {
+        did: member.did,
+        key: member.key,
+        lease: member.lease
+    });
+}
+/** Extend an incarnation's lease. A member may renew another member, never itself. */ export function createRenew({ signer, add, lease, ...base }) {
+    return buildEvent('ren', signer, base, {
+        add,
+        lease
+    });
+}
+/** End an incarnation's log authority. A member may remove another member, never itself. */ export function createRemove({ signer, add, ...base }) {
+    return buildEvent('rmv', signer, base, {
+        add
+    });
+}
+/**
+ * Deny an edge holder or a retired key. Root or any single member; a member may not target a member
+ * of its causal past, which removal covers instead.
+ */ export function createRevoke({ signer, target, ...base }) {
+    return buildEvent('rev', signer, base, {
+        x: target
+    });
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/** Length is bounded before the walk, so an oversized list costs one comparison. */ function isStringList(value, max) {
+    return Array.isArray(value) && value.length <= max && value.every((e)=>typeof e === 'string');
+}
+/** Unix seconds: a non-negative safe integer, so `"1800000000"` and `1.5` both fail. */ function isSeconds(value) {
+    return Number.isSafeInteger(value) && value >= 0;
+}
+function hasTypeFields(event) {
+    switch(event.t){
+        case 'add':
+            return typeof event.did === 'string' && typeof event.key === 'string' && isSeconds(event.lease);
+        case 'ren':
+            return typeof event.add === 'string' && isSeconds(event.lease);
+        case 'rmv':
+            return typeof event.add === 'string';
+        case 'rev':
+            return typeof event.x === 'string';
+        default:
+            return false;
+    }
+}
+/**
+ * Whether `value` has the shape of a signed epoch event: the envelope, the fields its type carries,
+ * the parent rules, and a canonical body within {@link MAX_EVENT_BYTES}. Total on anything
+ * `JSON.parse` yields, since an epoch event arrives from a peer or an untrusted store. A request-limit
+ * check: failing it rejects input and changes no state.
+ *
+ * Structure only. It says nothing about who signed, whether the signer may, or whether the parents
+ * exist -- those belong to {@link verifyEpochSignature} and the fold. `crit` must be exactly `true`:
+ * every type here is critical, and a known type declaring otherwise is a body whose envelope
+ * contradicts it. A `recoveryKey` on the envelope is refused rather than ignored -- only a reset
+ * reveals one, and a member nothing reads is a field that lies.
+ */ export function isEpochEventShape(value) {
+    if (!isRecord(value) || !isRecord(value.event)) {
+        return false;
+    }
+    const { event, sigs } = value;
+    if (!isStringList(sigs, MAX_EVENT_SIGNATURES) || sigs.length === 0 || value.recoveryKey !== undefined) {
+        return false;
+    }
+    if (event.v !== 1 || !EPOCH_EVENT_TYPES.has(event.t) || typeof event.i !== 'string' || !isSeconds(event.g) || typeof event.e !== 'string' || event.crit !== true || event.by !== undefined && typeof event.by !== 'string') {
+        return false;
+    }
+    const p = event.p;
+    if (!isStringList(p, MAX_EVENT_PARENTS) || p.length === 0 || new Set(p).size !== p.length) {
+        return false;
+    }
+    if (!hasTypeFields(event)) {
+        return false;
+    }
+    // Last: the only check whose cost grows with the body, and the one that needs the rest settled.
+    return isCanonicalizable(event) && canonicalBytes(event).length <= MAX_EVENT_BYTES;
+}
+/**
+ * Whether `signed` verifies under the signer the caller names. The fold names it from `by`: absent,
+ * the chain head's keys; present, the key the referenced add pinned.
+ *
+ * The signer kind must agree with `by`, so a root-signed body cannot pass as a member's or the
+ * reverse: a single-key root and a member are otherwise the same check, and an event whose `by` the
+ * caller did not consult would be authorised as whoever happened to be asked about. Root is n-of-n
+ * over `rootKeys` (via `verifySignatures`); a member signs alone, so exactly one signature, under the
+ * pinned key. Total: a malformed body or signature is `false`.
+ */ export function verifyEpochSignature(signed, signer) {
+    const { event, sigs } = signed;
+    if (!isRecord(event) || !Array.isArray(sigs) || sigs.length > MAX_EVENT_SIGNATURES) {
+        return false;
+    }
+    if ('rootKeys' in signer) {
+        return event.by === undefined && verifySignatures(event, sigs, signer.rootKeys);
+    }
+    // One key, and `verifySignatures` matches signatures to keys one for one: exactly one signature.
+    return sigs.length === 1 && typeof event.by === 'string' && verifySignatures(event, sigs, [
+        signer.memberKey
+    ]);
+}

package/lib/epoch.d.ts

@@ -0,0 +1,90 @@
+import { type EpochEvent } from './epoch-events.js';
+import { type SignedEvent } from './events.js';
+import type { KeyState } from './fold.js';
+/** A member-signed add. Only root admits members, so sock-puppets cannot renew each other forever. */
+export declare const ADD_NOT_ROOT = "only root may add a member";
+/** An add pinning a key on, or committed by, the generation's root chain, or the recovery key. */
+export declare const ADD_KEY_IS_ROOT = "member key is a root key";
+/** An add whose DID is not a `did:key` or long-form `did:peer:4` carrying exactly its pin. */
+export declare const ADD_DID_MISMATCH = "member DID does not carry its key";
+/** An add of a DID or key that a denial in its causal past targets. */
+export declare const ADD_KEY_DENIED = "member is denied in the causal state";
+/** An add of a key an effective member of its causal past already pins. */
+export declare const ADD_KEY_ALREADY_MEMBER = "member key is already an effective member";
+/** A member renewing an incarnation pinning its own key. */
+export declare const SELF_RENEW = "a member may not renew itself";
+/** A member removing an incarnation pinning its own key. */
+export declare const SELF_REMOVE = "a member may not remove itself";
+/** A renew or remove naming an add its causal past does not hold. */
+export declare const UNKNOWN_MEMBER = "target is not a member of the causal state";
+/** A member revoke targeting an effective member of its causal past: members leave through remove. */
+export declare const MEMBER_REVOKES_MEMBER = "a member may not revoke a member";
+/** A revoke denying a key the chain head publishes in `k` or `ka`. */
+export declare const REVOKE_NAMES_ROOT_KEY = "revoke targets a key the chain publishes";
+/**
+ * What a presentation fails with, as a whole, when the signatures on its copies that do not verify
+ * exceed {@link MAX_FAILED_SIGNATURES}. A request limit, so it shares `LOG_TOO_LARGE`'s prefix.
+ */
+export declare const TOO_MANY_FAILED_SIGNATURES = "controller log exceeds request limits: too many signatures fail to verify";
+export type EpochLimits = {
+    MAX_EPOCH_EVENTS: number;
+};
+/** What {@link foldEpoch} uses when a caller lowers nothing: pinned so a test can see it. */
+export declare const DEFAULT_EPOCH_LIMITS: EpochLimits;
+export type FoldEpochParams = {
+    did: string;
+    /** The chain's states, in order; the last is the anchor the epoch grew from. */
+    chainStates: Array<KeyState>;
+    /** Untrusted: whatever was presented as epoch events. */
+    events: Array<unknown>;
+    /**
+     * Copies this verifier authenticated itself and kept: its own memory, never a presentation. A
+     * trusted copy of an event of this epoch is taken as authentic without checking its signatures
+     * again, and stands in for every presented copy of the same body, which are then not checked
+     * either. Its signer is fixed by the epoch: a root event's keys are the chain event the epoch names,
+     * a member event's key the add or snapshot entry its `by` digest names, so a copy that verified
+     * once under this epoch verifies under it every time. Authorisation is still judged afresh.
+     */
+    trusted?: Array<unknown>;
+    /** Test-only: lowers a limit so saturation is reachable without thousands of signatures. */
+    limits?: Partial<EpochLimits>;
+};
+export type FoldEpochResult = {
+    ok: true;
+    head: KeyState;
+    /** Digests of the events that applied, parents first, ties by ascending digest. */
+    applied: Array<string>;
+    /** Well-formed events of this epoch whose parents never all applied. */
+    pending: number;
+    /**
+     * Refusals, counted by distinct event: an event presented any number of times counts once. An entry
+     * that is not an epoch event at all has no digest to dedupe by and counts once per entry.
+     */
+    rejected: number;
+};
+export type FoldEpochDetail = FoldEpochResult & {
+    /** Why each refused event was refused, by digest. Entries that are not events at all have no digest. */
+    reasons: Map<string, string>;
+    /**
+     * The copy that verified, for each applied digest: what may be remembered of the event. A copy of a
+     * body under other signatures shares its digest, so the digest alone does not say which to keep.
+     */
+    authentic: Map<string, SignedEvent<EpochEvent>>;
+};
+/**
+ * A presentation refused as a whole by a request limit on the work it asked for. Never a judgement on
+ * any one event, so nothing about the epoch is learned from it.
+ */
+export type FoldEpochRefusal = {
+    ok: false;
+    reason: string;
+};
+/**
+ * Merge the current epoch into the chain's last state. Total: whatever `events` holds, the result is
+ * a head or a refusal, never a throw -- an entry that is not a valid epoch event is counted and
+ * dropped. The one refusal is the request limit on failed signatures ({@link TOO_MANY_FAILED_SIGNATURES}),
+ * which `trusted` copies never count towards.
+ */
+export declare function foldEpochDetailed(params: FoldEpochParams): FoldEpochDetail | FoldEpochRefusal;
+/** {@link foldEpochDetailed} without the per-event reasons and copies. */
+export declare function foldEpoch(params: FoldEpochParams): FoldEpochResult | FoldEpochRefusal;