@aiwg/cli 2026.9.20 → 2026.9.21

package/dist/src/effects/checkpoint-sinks.js

@@ -0,0 +1,94 @@
+/**
+ * Independent checkpoint sinks. A local chain alone cannot detect deletion of
+ * a whole segment or of its tail, so every checkpoint is also published to a
+ * sink the ledger directory does not control.
+ *
+ * - `gitRefCheckpointSink` (the default) stores the canonical checkpoint as a
+ *   git blob and moves `refs/aiwg/effects/<subsystem>/checkpoint` to it with a
+ *   compare-and-swap `update-ref`.
+ * - `memoryCheckpointSink` is for tests and embedding hosts.
+ * - Other sinks (for example the #1567 operator-decision audit) implement the
+ *   same `CheckpointSink` port.
+ */
+import { spawn } from 'node:child_process';
+import { canonicalJson } from '../security/artifact-trust.js';
+import { EffectLedgerError } from './errors.js';
+const sinkError = (message) => new EffectLedgerError('internal', message, 'checkpoint-sink-unavailable');
+function defaultGitRunner(repoDir) {
+    return (args, stdin = '') => new Promise((resolve, reject) => {
+        const child = spawn('git', ['-C', repoDir, ...args], { stdio: ['pipe', 'pipe', 'ignore'], windowsHide: true, env: { ...process.env, GIT_TERMINAL_PROMPT: '0' } });
+        const chunks = [];
+        child.stdout.on('data', (chunk) => chunks.push(chunk));
+        child.once('error', reject);
+        child.stdin.once('error', () => { });
+        child.once('close', code => resolve({ stdout: Buffer.concat(chunks).toString('utf8'), exitCode: code ?? 1 }));
+        child.stdin.end(stdin);
+    });
+}
+export function gitRefCheckpointSink(options) {
+    const ref = options.ref ?? `refs/aiwg/effects/${options.subsystem}/checkpoint`;
+    if (!/^refs\/[A-Za-z0-9._/-]+$/.test(ref) || ref.includes('..'))
+        throw new EffectLedgerError('usage', 'Invalid checkpoint ref', 'invalid-ref');
+    const git = options.runner ?? defaultGitRunner(options.repoDir);
+    const current = async () => {
+        const result = await git(['rev-parse', '-q', '--verify', ref]);
+        return result.exitCode === 0 ? result.stdout.trim() : null;
+    };
+    return {
+        name: 'git-ref',
+        async publish(checkpoint) {
+            let previous;
+            try {
+                previous = await current();
+            }
+            catch {
+                throw sinkError('Git checkpoint sink is unavailable');
+            }
+            const stored = await git(['hash-object', '-w', '--stdin'], `${canonicalJson(checkpoint)}\n`).catch(() => null);
+            const oid = stored?.stdout.trim();
+            if (!stored || stored.exitCode !== 0 || !oid || !/^[a-f0-9]{40,64}$/.test(oid))
+                throw sinkError('Git checkpoint sink could not store the checkpoint');
+            const moved = await git(['update-ref', '-m', `aiwg effect checkpoint ${checkpoint.sequence}`, ref, oid, previous ?? '']).catch(() => null);
+            if (!moved || moved.exitCode !== 0)
+                throw sinkError('Git checkpoint sink ref moved concurrently or could not be updated');
+            return { sink: 'git-ref', reference: `${ref}@${oid}` };
+        },
+        async latest() {
+            let head;
+            try {
+                head = await current();
+            }
+            catch {
+                throw sinkError('Git checkpoint sink is unavailable');
+            }
+            if (!head)
+                return null;
+            const blob = await git(['cat-file', 'blob', head]).catch(() => null);
+            if (!blob || blob.exitCode !== 0)
+                throw sinkError('Git checkpoint sink ref is unreadable');
+            try {
+                return JSON.parse(blob.stdout);
+            }
+            catch {
+                throw sinkError('Git checkpoint sink holds a malformed checkpoint');
+            }
+        },
+    };
+}
+/** In-memory sink. `published` holds every checkpoint in publication order. */
+export function memoryCheckpointSink() {
+    const published = [];
+    return {
+        name: 'memory',
+        published,
+        async publish(checkpoint) {
+            published.push(structuredClone(checkpoint));
+            return { sink: 'memory', reference: `memory#${published.length - 1}` };
+        },
+        async latest(scope) {
+            const match = [...published].reverse().find(entry => canonicalJson(entry.scope) === canonicalJson(scope));
+            return match ? structuredClone(match) : null;
+        },
+    };
+}
+//# sourceMappingURL=checkpoint-sinks.js.map

package/dist/src/effects/checkpoint.js

@@ -0,0 +1,76 @@
+/**
+ * Signed checkpoints over every writer's segment head, published first to the
+ * independent sink and then written locally.
+ *
+ * @see docs/contracts/effect-ledger.v1.md "Storage layout"
+ */
+import { join } from 'node:path';
+import { canonicalJson } from '../security/artifact-trust.js';
+import { publishExclusive } from '../storage/protected-files.js';
+import { EffectLedgerError, integrityError, usageError } from './errors.js';
+import { sha256Digest } from './identity.js';
+import { activeKey, assertKeyring, keyringDigest, keyValidAt } from './keyring.js';
+import { readAllSegments, readKeyring } from './reader.js';
+import { assertEffectSchema } from './schema.js';
+import { ensureLedgerDirectories, withLedgerLock } from './store.js';
+import { CHECKPOINT_PAYLOAD_TYPE, CHECKPOINT_SCHEMA_VERSION } from './types.js';
+import { checkpointDigest, readLocalCheckpoints, verifyLedger } from './verify.js';
+/**
+ * Checkpoint the ledger. The ledger must verify first (against the previous
+ * checkpoint), so a checkpoint never anchors a truncated or edited ledger.
+ */
+export async function writeCheckpoint(ledger, options = {}) {
+    const sink = options.sink ?? ledger.sink;
+    const paths = ledger.paths();
+    await ensureLedgerDirectories(paths);
+    const key = await ledger.signingKey();
+    return withLedgerLock(paths, 'checkpoint', ledger.lockTimeoutMs, async () => {
+        const verification = await verifyLedger(ledger, { sink });
+        if (!verification.ok)
+            throw integrityError(verification.failures[0].reason, 'Effect ledger failed verification; refusing to checkpoint');
+        if (verification.warnings.includes('checkpoint-sink-unreadable')) {
+            throw new EffectLedgerError('internal', 'Checkpoint sink is unavailable; no checkpoint was written', 'checkpoint-sink-unavailable');
+        }
+        const keyring = await readKeyring(paths);
+        assertKeyring(keyring, ledger.scope);
+        const createdAt = ledger.now();
+        const active = activeKey(keyring);
+        if (active.keyid !== key.keyid || !keyValidAt(active, createdAt)) {
+            throw new EffectLedgerError('key-unavailable', 'The loaded signing key is not the active ledger key at this time', 'key-not-active');
+        }
+        const segments = await readAllSegments(paths);
+        const writers = segments.filter(segment => segment.lines.length > 0).map(segment => ({
+            writer: segment.writer,
+            segment: `segments/${segment.writer}.jsonl`,
+            count: segment.lines.length,
+            headHash: segment.lines.at(-1).decoded.line.recordHash,
+        }));
+        if (!writers.length)
+            throw usageError('The effect ledger has no records to checkpoint', 'nothing-to-checkpoint');
+        const local = (await readLocalCheckpoints(paths)).at(-1)?.value;
+        const remote = await sink.latest(ledger.scope);
+        const previous = [local, remote].filter((value) => !!value)
+            .sort((a, b) => b.sequence - a.sequence)[0];
+        const body = {
+            schemaVersion: CHECKPOINT_SCHEMA_VERSION,
+            scope: structuredClone(ledger.scope),
+            sequence: previous ? previous.sequence + 1 : 0,
+            createdAt,
+            writers,
+            root: sha256Digest(canonicalJson(writers)),
+            keyringDigest: keyringDigest(keyring),
+            previousCheckpoint: previous ? checkpointDigest(previous) : null,
+        };
+        const checkpoint = {
+            ...body,
+            signatures: [{ keyid: key.keyid, sig: key.signPae(CHECKPOINT_PAYLOAD_TYPE, Buffer.from(canonicalJson(body), 'utf8')) }],
+        };
+        assertEffectSchema('checkpoint', checkpoint);
+        const receipt = await sink.publish(checkpoint);
+        const written = await publishExclusive(paths.checkpoints, join(paths.checkpoints, `${checkpoint.sequence}.json`), `${JSON.stringify(checkpoint, null, 2)}\n`, 'checkpoint');
+        if (!written)
+            throw integrityError('checkpoint-sequence-exists');
+        return { checkpoint, digest: checkpointDigest(checkpoint), sink: receipt };
+    });
+}
+//# sourceMappingURL=checkpoint.js.map

package/dist/src/effects/decision-links.js

@@ -0,0 +1,54 @@
+/**
+ * #1567 composition: effect records link the operator decisions that
+ * authorized them through `links.operatorDecisionEventId` and
+ * `links.operatorDecisionRecordHash`. This module checks those links against
+ * an operator-decision audit chain. It is read-only on both sides: there is
+ * no write coupling between the ledger and the decision store.
+ *
+ * @see docs/contracts/effect-ledger.v1.md "Composition"
+ * @see docs/contracts/operator-decision-audit.v1.md
+ */
+import { readAllSegments } from './reader.js';
+/** The operator-decision links a ledger record carries, or null. */
+export function decisionLinkOf(links) {
+    if (!links || (!links.operatorDecisionEventId && !links.operatorDecisionRecordHash))
+        return null;
+    return {
+        ...(links.operatorDecisionEventId ? { eventId: links.operatorDecisionEventId } : {}),
+        ...(links.operatorDecisionRecordHash ? { recordHash: links.operatorDecisionRecordHash } : {}),
+    };
+}
+/**
+ * Check every operator-decision link in the ledger against `decisions`. A
+ * linked event ID must exist; a linked record hash must equal that event's
+ * `record_hash`; a record hash without an event ID is refused. The caller
+ * verifies the decision chain itself (`verifyDecisionChain`).
+ */
+export async function verifyDecisionLinks(ledger, decisions) {
+    const byId = new Map(decisions.map(record => [record.event_id, record.record_hash]));
+    const failures = [];
+    const events = new Set();
+    let linked = 0;
+    for (const segment of await readAllSegments(ledger.paths())) {
+        for (const line of segment.lines) {
+            const predicate = line.decoded?.statement.predicate;
+            const link = decisionLinkOf(predicate?.links);
+            if (!predicate || !link)
+                continue;
+            linked += 1;
+            const at = { writer: segment.writer, seq: line.index, effectId: predicate.effectId };
+            if (!link.eventId) {
+                failures.push({ ...at, reason: 'decision-record-hash-orphan' });
+                continue;
+            }
+            events.add(link.eventId);
+            const recordHash = byId.get(link.eventId);
+            if (recordHash === undefined)
+                failures.push({ ...at, reason: 'decision-event-missing', operatorDecisionEventId: link.eventId });
+            else if (link.recordHash && link.recordHash !== recordHash)
+                failures.push({ ...at, reason: 'decision-record-hash-mismatch', operatorDecisionEventId: link.eventId });
+        }
+    }
+    return { ok: failures.length === 0, linked, events: events.size, failures };
+}
+//# sourceMappingURL=decision-links.js.map

package/dist/src/effects/errors.js

@@ -0,0 +1,48 @@
+/**
+ * Effect ledger error taxonomy, bound to the v1 exit codes.
+ *
+ * Messages are fixed, reference-only text: they never echo payloads, keys,
+ * vault locators or rejected material.
+ *
+ * @see docs/contracts/effect-ledger.v1.md "CLI and exit codes"
+ */
+/** Exit codes pinned by the effect ledger v1 contract. */
+export const EFFECT_EXIT_CODES = Object.freeze({
+    ok: 0,
+    internal: 1,
+    usage: 2,
+    absent: 3,
+    unknown: 4,
+    conflict: 5,
+    integrity: 6,
+    artifactRootUnavailable: 7,
+});
+const EXIT_BY_CODE = {
+    internal: EFFECT_EXIT_CODES.internal,
+    usage: EFFECT_EXIT_CODES.usage,
+    conflict: EFFECT_EXIT_CODES.conflict,
+    integrity: EFFECT_EXIT_CODES.integrity,
+    'artifact-root-unavailable': EFFECT_EXIT_CODES.artifactRootUnavailable,
+    'key-unavailable': EFFECT_EXIT_CODES.internal,
+    'lock-timeout': EFFECT_EXIT_CODES.internal,
+    'purge-refused': EFFECT_EXIT_CODES.usage,
+};
+export class EffectLedgerError extends Error {
+    code;
+    reason;
+    exitCode;
+    constructor(code, message, reason) {
+        super(message);
+        this.code = code;
+        this.reason = reason;
+        this.name = 'EffectLedgerError';
+        this.exitCode = EXIT_BY_CODE[code];
+    }
+    toJSON() {
+        return { code: this.code, ...(this.reason ? { reason: this.reason } : {}), message: this.message, exitCode: this.exitCode };
+    }
+}
+export const usageError = (message, reason) => new EffectLedgerError('usage', message, reason);
+export const integrityError = (reason, message = 'Effect ledger integrity check failed') => new EffectLedgerError('integrity', message, reason);
+export const conflictError = (message = 'Effect ID already recorded with a different payload digest') => new EffectLedgerError('conflict', message, 'payload-digest-conflict');
+//# sourceMappingURL=errors.js.map

package/dist/src/effects/identity.js

@@ -0,0 +1,178 @@
+/**
+ * Effect identity: the `aiwg.effect/v1` derivation, the contract-registered
+ * adapter derivations (`d13.review/v1`), payload digests and input grammar.
+ *
+ * Every canonical form is RFC 8785 JSON from `artifact-trust.canonicalJson`.
+ *
+ * @see docs/contracts/effect-ledger.v1.md "Effect identity"
+ */
+import { createHash } from 'node:crypto';
+import { canonicalJson } from '../security/artifact-trust.js';
+import { usageError } from './errors.js';
+import { CORE_EFFECT_KINDS, EFFECT_ID_DERIVATION_NAMES, EFFECT_SUBSYSTEMS, } from './types.js';
+const BASE32_ALPHABET = 'abcdefghijklmnopqrstuvwxyz234567';
+export const EFFECT_ID_V1_PATTERN = /^eff1_[a-z2-7]{51}[aq]$/;
+export const D13_REVIEW_ID_PATTERN = /^sha256:[a-f0-9]{64}$/;
+export const SHA256_DIGEST_PATTERN = /^sha256:[a-f0-9]{64}$/;
+export const WRITER_ID_PATTERN = /^[a-z0-9][a-z0-9-]{0,63}$/;
+const IDENTIFIER_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._:/@-]{0,255}$/;
+const EXTENSION_KIND_PATTERN = /^x\.[a-z0-9][a-z0-9-]*(?:\.[a-z0-9][a-z0-9-]*)+$/;
+const TARGET_PATTERN = /^(?:gitea|github|git|git-tag|file|release|decision|review|x-[a-z0-9-]+):[^\s]+$/;
+const CONTEXT_KEY_PATTERN = /^[A-Za-z][A-Za-z0-9_]{0,63}$/;
+const D13_CONTEXT_KEYS = ['continuationId', 'proposalVersion', 'reviewId'];
+const sha256Hex = (bytes) => createHash('sha256').update(bytes).digest('hex');
+/** `"sha256:"` plus lowercase hex SHA-256 of the bytes (strings are UTF-8). */
+export function sha256Digest(bytes) {
+    return `sha256:${sha256Hex(bytes)}`;
+}
+/** Unpadded lowercase RFC 4648 section 6 base32, most significant bit first. */
+export function base32Lower(bytes) {
+    let bits = 0;
+    let value = 0;
+    let out = '';
+    for (const byte of bytes) {
+        value = ((value << 8) | byte) & 0xffff;
+        bits += 8;
+        while (bits >= 5) {
+            out += BASE32_ALPHABET[(value >>> (bits - 5)) & 31];
+            bits -= 5;
+        }
+    }
+    if (bits > 0)
+        out += BASE32_ALPHABET[(value << (5 - bits)) & 31];
+    return out;
+}
+export function isCoreEffectKind(kind) {
+    return CORE_EFFECT_KINDS.includes(kind);
+}
+export function isEffectKind(kind) {
+    return typeof kind === 'string' && (isCoreEffectKind(kind) || (kind.length <= 128 && EXTENSION_KIND_PATTERN.test(kind)));
+}
+export function assertEffectScope(scope) {
+    const value = scope;
+    if (!value || typeof value !== 'object' || Array.isArray(value)
+        || Object.keys(value).sort().join(',') !== 'project,subsystem,tenant'
+        || typeof value.tenant !== 'string' || !IDENTIFIER_PATTERN.test(value.tenant)
+        || typeof value.project !== 'string' || !IDENTIFIER_PATTERN.test(value.project)
+        || !EFFECT_SUBSYSTEMS.includes(value.subsystem)) {
+        throw usageError('Effect scope must be {tenant, project, subsystem} with a known subsystem', 'invalid-scope');
+    }
+}
+export function assertWriterId(writer) {
+    if (typeof writer !== 'string' || !WRITER_ID_PATTERN.test(writer))
+        throw usageError('Effect writer ID is invalid', 'invalid-writer');
+}
+export function assertEffectKind(kind) {
+    if (!isEffectKind(kind))
+        throw usageError('Unknown effect kind', 'unknown-kind');
+}
+export function assertEffectTarget(target) {
+    if (typeof target !== 'string' || target.length > 1024 || !TARGET_PATTERN.test(target)) {
+        throw usageError('Effect target must be a <scheme>:<ref> reference', 'invalid-target');
+    }
+}
+export function assertEffectContext(context) {
+    if (!context || typeof context !== 'object' || Array.isArray(context))
+        throw usageError('Effect context must be a flat object', 'invalid-context');
+    const entries = Object.entries(context);
+    if (entries.length > 16)
+        throw usageError('Effect context has more than 16 members', 'invalid-context');
+    for (const [key, value] of entries) {
+        const scalar = (typeof value === 'string' && value.length <= 256)
+            || (typeof value === 'number' && Number.isSafeInteger(value))
+            || typeof value === 'boolean';
+        if (!CONTEXT_KEY_PATTERN.test(key) || !scalar)
+            throw usageError('Effect context members must be named scalars', 'invalid-context');
+    }
+}
+export function assertPayloadDigest(value) {
+    if (typeof value !== 'string' || !SHA256_DIGEST_PATTERN.test(value))
+        throw usageError('Payload digest must be sha256:<hex>', 'invalid-payload-digest');
+}
+/** Digest the exact bytes an effect sends, or `canonicalJson` of a structured request. */
+export function payloadDigest(payload) {
+    if (typeof payload === 'string' || payload instanceof Uint8Array)
+        return sha256Digest(payload);
+    return sha256Digest(canonicalJson(payload));
+}
+function assertIdentityInput(input) {
+    if (!input || typeof input !== 'object')
+        throw usageError('Effect identity input is required', 'invalid-identity');
+    assertEffectScope(input.scope);
+    assertEffectKind(input.kind);
+    assertEffectTarget(input.target);
+    assertEffectContext(input.context);
+}
+const aiwgEffectV1 = Object.freeze({
+    name: 'aiwg.effect/v1',
+    pattern: EFFECT_ID_V1_PATTERN,
+    permitsKind: (kind) => kind !== 'decision.review.continuation',
+    derive(input) {
+        assertIdentityInput(input);
+        if (input.kind === 'decision.review.continuation')
+            throw usageError('decision.review.continuation uses the d13.review/v1 derivation', 'derivation-kind-mismatch');
+        const canonical = canonicalJson({ v: 1, scope: input.scope, kind: input.kind, target: input.target, context: input.context });
+        return `eff1_${base32Lower(createHash('sha256').update(canonical, 'utf8').digest())}`;
+    },
+});
+/**
+ * `d13.review/v1`: exactly D13's `reviewDigest({reviewId, continuationId,
+ * proposalVersion})` (`src/decision/review/validate.ts`), so persisted reviews
+ * keep their identity.
+ */
+const d13ReviewV1 = Object.freeze({
+    name: 'd13.review/v1',
+    pattern: D13_REVIEW_ID_PATTERN,
+    permitsKind: (kind) => kind === 'decision.review.continuation',
+    derive(input) {
+        assertIdentityInput(input);
+        const context = input.context;
+        if (input.kind !== 'decision.review.continuation' || input.scope.subsystem !== 'review'
+            || Object.keys(context).sort().join(',') !== D13_CONTEXT_KEYS.join(',')
+            || typeof context.reviewId !== 'string' || !context.reviewId
+            || typeof context.continuationId !== 'string' || !context.continuationId
+            || typeof context.proposalVersion !== 'number' || !Number.isSafeInteger(context.proposalVersion) || context.proposalVersion < 1) {
+            throw usageError('d13.review/v1 needs kind decision.review.continuation, subsystem review and context {reviewId, continuationId, proposalVersion}', 'derivation-input-invalid');
+        }
+        const identity = { reviewId: context.reviewId, continuationId: context.continuationId, proposalVersion: context.proposalVersion };
+        return sha256Digest(canonicalJson(identity));
+    },
+});
+/**
+ * Contract-registered derivations. Registration is closed: a new derivation
+ * needs a contract revision (and a schema `idDerivation` value), so this map is
+ * frozen rather than extensible at runtime.
+ */
+export const EFFECT_ID_DERIVATIONS = Object.freeze({
+    'aiwg.effect/v1': aiwgEffectV1,
+    'd13.review/v1': d13ReviewV1,
+});
+export function effectIdDerivation(name) {
+    if (!EFFECT_ID_DERIVATION_NAMES.includes(name))
+        throw usageError('Unknown effect ID derivation', 'unknown-derivation');
+    return EFFECT_ID_DERIVATIONS[name];
+}
+/** The derivation a kind uses by default. */
+export function defaultDerivationFor(kind) {
+    return kind === 'decision.review.continuation' ? 'd13.review/v1' : 'aiwg.effect/v1';
+}
+/**
+ * Derive an effect ID. Attempt, time, actor, host and payload are not inputs.
+ * `derivation` defaults to the kind's registered derivation.
+ */
+export function effectId(input, derivation = defaultDerivationFor(input?.kind)) {
+    return effectIdDerivation(derivation).derive(input);
+}
+/** Strict reader-side check. Uppercase, padding, other lengths and non-zero trailing bits are rejected, never normalized. */
+export function isValidEffectId(id, derivation) {
+    if (typeof id !== 'string')
+        return false;
+    if (derivation)
+        return effectIdDerivation(derivation).pattern.test(id);
+    return EFFECT_ID_V1_PATTERN.test(id) || D13_REVIEW_ID_PATTERN.test(id);
+}
+export function assertEffectId(id, derivation) {
+    if (!isValidEffectId(id, derivation))
+        throw usageError('Malformed effect ID', 'malformed-effect-id');
+}
+//# sourceMappingURL=identity.js.map

package/dist/src/effects/index.js

@@ -0,0 +1,25 @@
+/**
+ * AIWG effect ledger core library (#2717, epic #2714).
+ *
+ * A signed proof and deduplication index for side effects. It is not an
+ * exactly-once mechanism and it never authorizes an effect.
+ *
+ * @see docs/contracts/effect-ledger.v1.md
+ * @see docs/architecture/adr-effect-ledger.md
+ */
+export * from './types.js';
+export { EFFECT_EXIT_CODES, EffectLedgerError, } from './errors.js';
+export { D13_REVIEW_ID_PATTERN, EFFECT_ID_DERIVATIONS, EFFECT_ID_V1_PATTERN, assertEffectId, base32Lower, defaultDerivationFor, effectId, effectIdDerivation, isEffectKind, isValidEffectId, payloadDigest, sha256Digest as effectSha256Digest, } from './identity.js';
+export { DEFAULT_LEDGER_KEY_SERVICE, LEDGER_TEST_KEY_ENV, LedgerSigningKey, credentialStoreKeyProvider, environmentTestKeyProvider, generateLedgerKeySecret, staticKeyProvider, } from './keys.js';
+export { activeKey, keyValidAt, keyringDigest, keyringFailure } from './keyring.js';
+export { EffectLedger, effectOutputJson, initLedgerKeyring, lookupEffect, readLedgerKeyring, openEffectLedger, reconcileEffect, recordIntent, recordOutcome, recordReconciled, rotateKey, } from './ledger.js';
+export * from './verifiers/index.js';
+export { gitRefCheckpointSink, memoryCheckpointSink, } from './checkpoint-sinks.js';
+export { writeCheckpoint } from './checkpoint.js';
+export { checkpointDigest, verifyLedger, } from './verify.js';
+export { EFFECT_RETENTION_POLICY, purgeEffect } from './lifecycle.js';
+export { LEDGER_LOCK_NAME_PATTERN, LOCK_RECOVERY_KIND, LOCK_RECOVERY_VERIFIER_VERSION, inspectLedgerLock, inspectLedgerLocks, ledgerLockRecoveryVerifier, lockRecoveryTarget, recoverStaleLedgerLock, } from './lock-recovery.js';
+export { assertDigestOnly, containsRestrictedMaterial } from './redaction.js';
+export { EFFECT_SCHEMA_IDS, effectSchemaErrors, isEffectSchemaValid } from './schema.js';
+export { decisionLinkOf, verifyDecisionLinks, } from './decision-links.js';
+//# sourceMappingURL=index.js.map

package/dist/src/effects/keyring.js

@@ -0,0 +1,160 @@
+/**
+ * Effect ledger keyring: public Ed25519 keys with validity windows, extended
+ * only by rotations signed by both the prior and the successor key.
+ *
+ * @see docs/contracts/effect-ledger.v1.md "Signing and keyring"
+ */
+import { canonicalJson, decodeBase64, dssePae, publicKeyFingerprint, verifyBytes } from '../security/artifact-trust.js';
+import { integrityError, usageError } from './errors.js';
+import { sha256Digest } from './identity.js';
+import { isEffectSchemaValid } from './schema.js';
+import { KEYRING_SCHEMA_VERSION, ROTATION_PAYLOAD_TYPE, ROTATION_SCHEMA_VERSION, } from './types.js';
+const time = (value) => Date.parse(value);
+/** `"sha256:"` plus hex SHA-256 of `canonicalJson(keyring)`, as recorded in checkpoints. */
+export function keyringDigest(keyring) {
+    return sha256Digest(canonicalJson(keyring));
+}
+/** `validFrom ≤ t < validUntil`, and before `revokedAt` for a revoked key. */
+export function keyValidAt(key, at) {
+    const t = time(at);
+    if (!Number.isFinite(t) || t < time(key.validFrom))
+        return false;
+    if (key.validUntil !== undefined && t >= time(key.validUntil))
+        return false;
+    if (key.status === 'revoked' && (key.revokedAt === undefined || t >= time(key.revokedAt)))
+        return false;
+    return true;
+}
+function signatureValid(publicKey, payloadType, payload, sig) {
+    try {
+        return verifyBytes('ed25519', publicKey, dssePae(payloadType, payload), decodeBase64(sig, 'signature'));
+    }
+    catch {
+        return false;
+    }
+}
+/** Check one DSSE signature against the keyring at signing time `at`. */
+export function checkSignature(keyring, keyid, sig, payloadType, payload, at) {
+    const key = keyring.keys.find(entry => entry.keyid === keyid);
+    if (!key)
+        return 'unknown-keyid';
+    if (!signatureValid(key.publicKey, payloadType, payload, sig))
+        return 'signature-invalid';
+    if (!keyValidAt(key, at))
+        return 'key-window';
+    return 'ok';
+}
+function rotationBody(rotation) {
+    const { signatures: _signatures, ...body } = rotation;
+    return body;
+}
+/**
+ * Structural and cryptographic keyring check. Returns a failure reason, or
+ * null when the keyring is a genesis key extended only by valid rotations.
+ */
+export function keyringFailure(keyring, scope) {
+    if (!isEffectSchemaValid('keyring', keyring))
+        return 'keyring-schema-invalid';
+    const ring = keyring;
+    if (scope && canonicalJson(ring.scope) !== canonicalJson(scope))
+        return 'keyring-scope-mismatch';
+    const byId = new Map();
+    for (const key of ring.keys) {
+        if (byId.has(key.keyid))
+            return 'keyring-duplicate-keyid';
+        try {
+            if (`sha256:${publicKeyFingerprint(key.publicKey)}` !== key.keyid)
+                return 'keyring-keyid-mismatch';
+        }
+        catch {
+            return 'keyring-keyid-mismatch';
+        }
+        byId.set(key.keyid, key);
+    }
+    const introduced = new Set(ring.rotations.map(rotation => rotation.to));
+    const genesis = ring.keys.filter(key => !introduced.has(key.keyid));
+    if (genesis.length !== 1 || ring.keys.length !== ring.rotations.length + 1)
+        return 'keyring-unrotated-key';
+    let current = genesis[0];
+    let lastEffective = -Infinity;
+    for (const [index, rotation] of ring.rotations.entries()) {
+        if (rotation.sequence !== index + 1)
+            return 'keyring-rotation-sequence';
+        const successor = byId.get(rotation.to);
+        const effective = time(rotation.effectiveAt);
+        if (rotation.from !== current.keyid || !successor || successor.keyid === current.keyid)
+            return 'keyring-rotation-chain';
+        if (!(effective > lastEffective) || current.validUntil === undefined || time(current.validUntil) !== effective
+            || time(successor.validFrom) !== effective)
+            return 'keyring-rotation-window';
+        const payload = Buffer.from(canonicalJson(rotationBody(rotation)), 'utf8');
+        const prior = rotation.signatures.find(entry => entry.role === 'prior');
+        const next = rotation.signatures.find(entry => entry.role === 'successor');
+        if (!prior || prior.keyid !== current.keyid || !signatureValid(current.publicKey, ROTATION_PAYLOAD_TYPE, payload, prior.sig))
+            return 'keyring-rotation-prior-signature';
+        if (!next || next.keyid !== successor.keyid || !signatureValid(successor.publicKey, ROTATION_PAYLOAD_TYPE, payload, next.sig))
+            return 'keyring-rotation-successor-signature';
+        current = successor;
+        lastEffective = effective;
+    }
+    return null;
+}
+export function assertKeyring(keyring, scope) {
+    const failure = keyringFailure(keyring, scope);
+    if (failure)
+        throw integrityError(failure, 'Effect ledger keyring failed verification');
+}
+/** The key currently allowed to sign: the last one in the rotation chain. */
+export function activeKey(keyring) {
+    const last = keyring.rotations.at(-1);
+    const keyid = last ? last.to : keyring.keys[0].keyid;
+    return keyring.keys.find(key => key.keyid === keyid);
+}
+export function createGenesisKeyring(scope, key, validFrom) {
+    return {
+        schemaVersion: KEYRING_SCHEMA_VERSION,
+        scope: structuredClone(scope),
+        keys: [{ keyid: key.keyid, algorithm: 'ed25519', publicKey: key.publicKey, validFrom, status: 'active' }],
+        rotations: [],
+    };
+}
+/**
+ * Extend `keyring` with a rotation from `prior` (which must be the active key)
+ * to `successor`, signed by both. The prior key's window closes at
+ * `effectiveAt`; records it signed earlier stay verifiable.
+ */
+export function rotateKeyring(keyring, prior, successor, effectiveAt, reason = 'scheduled') {
+    assertKeyring(keyring);
+    const current = activeKey(keyring);
+    if (current.keyid !== prior.keyid)
+        throw usageError('Only the active ledger key can sign a rotation', 'rotation-prior-not-active');
+    if (keyring.keys.some(key => key.keyid === successor.keyid))
+        throw usageError('The successor key is already in the keyring', 'rotation-key-reused');
+    if (!(time(effectiveAt) > time(current.validFrom)))
+        throw usageError('A rotation must take effect after the active key became valid', 'rotation-effective-at');
+    const body = {
+        schemaVersion: ROTATION_SCHEMA_VERSION,
+        sequence: keyring.rotations.length + 1,
+        from: prior.keyid,
+        to: successor.keyid,
+        effectiveAt,
+        reason,
+    };
+    const payload = Buffer.from(canonicalJson(body), 'utf8');
+    const next = structuredClone(keyring);
+    const retired = next.keys.find(key => key.keyid === prior.keyid);
+    retired.validUntil = effectiveAt;
+    if (retired.status === 'active')
+        retired.status = 'retired';
+    next.keys.push({ keyid: successor.keyid, algorithm: 'ed25519', publicKey: successor.publicKey, validFrom: effectiveAt, status: 'active' });
+    next.rotations.push({
+        ...body,
+        signatures: [
+            { role: 'prior', keyid: prior.keyid, sig: prior.signPae(ROTATION_PAYLOAD_TYPE, payload) },
+            { role: 'successor', keyid: successor.keyid, sig: successor.signPae(ROTATION_PAYLOAD_TYPE, payload) },
+        ],
+    });
+    assertKeyring(next);
+    return next;
+}
+//# sourceMappingURL=keyring.js.map