keri-ts 1.0.0 → 2.0.0

package/esm/keri/npm/src/app/credentials/credential-importing.js

@@ -0,0 +1,201 @@
+/** Finite credential-bundle intake; protocol owners retain and recover their own pending evidence. */
+import { Ilks, parse, SerderACDC, SerderKERI } from "cesr-ts";
+import { action, call, ensure, race } from "effection";
+import { consoleLogger } from "../../core/logger.js";
+import { rethrowCleanupFailure } from "../runtime/abortable.js";
+import { chunkBytes } from "../transport/byte-source.js";
+/**
+ * Dispatch each frame once, then recover local dependencies through their existing escrow owners.
+ * This operation owns its parser/Kevery and starts no network, mailbox or host workers.
+ * Later input failures preserve earlier accepted state. Receipts, replies and other messages still
+ * use normal dispatch; absence of an importer acceptance lookup is not an additional refusal policy.
+ *
+ * @param protocol Borrowed protocol dispatcher, sharing reger with its TEL/credential handlers.
+ * @param reger Borrowed credential/TEL store whose accepted records establish the result.
+ * @param bytes Borrowed finite CESR bundle; parser chunks are copied during intake.
+ * @param clock Borrowed timer implementation for the deadline and cooperative yields between sweeps.
+ * @param timeoutMs Positive finite post-EOF settlement limit in milliseconds, default 5000; floored with a one-millisecond minimum before intake.
+ * @returns Accepted-record observations after joined input/handler cleanup. Settlement stops when all observed records are accepted, or the deadline expires.
+ * @throws Parser, storage, handler and cleanup failures propagate with partial accepted state intact. Cancellation joins active work; a deadline cannot interrupt synchronous owner work mid-sweep.
+ */
+export function* importCredentialStream(protocol, reger, bytes, clock, timeoutMs = 5_000) {
+    if (!Number.isFinite(timeoutMs) || timeoutMs <= 0)
+        throw new RangeError("Import timeout must be finite and positive");
+    const settlementMs = Math.max(1, Math.floor(timeoutMs));
+    if (protocol.vry?.reger !== reger || protocol.tvy?.reger !== reger) {
+        throw new TypeError("Credential import requires TEL and credential processors sharing its Reger");
+    }
+    const targets = yield* readImportTargets(protocol, reger, bytes, protocol.makeKevery());
+    /** Read current acceptance; an earlier refused duplicate cannot override a persisted accepted record. */
+    const unaccepted = () => targets.filter((target) => !importTargetAccepted(target, protocol, reger)).map(({ said }) => said);
+    let expired = false;
+    if (unaccepted().length) {
+        expired = yield* race([
+            // Register the deadline before entering the first potentially suspending escrow owner.
+            action((resolve) => {
+                const timer = clock.setTimeout(() => resolve(true), settlementMs);
+                return () => clock.clearTimeout(timer);
+            }),
+            call(function* () {
+                while (true) {
+                    yield* protocol.processEscrowsOnce();
+                    if (!unaccepted().length)
+                        return false;
+                    // Yield between ordinary sweeps; acceptance or the elapsed deadline ends settlement.
+                    yield* action((resolve) => {
+                        const timer = clock.setTimeout(() => resolve(), 1);
+                        return () => clock.clearTimeout(timer);
+                    });
+                }
+            }),
+        ]);
+    }
+    // The losing race child has joined cleanup before these final accepted-state reads.
+    const remaining = unaccepted();
+    if (expired) {
+        consoleLogger.warn("Credential import settlement deadline expired", {
+            timeoutMs: settlementMs,
+            unaccepted: remaining,
+        });
+    }
+    return {
+        saved: targets.filter((target) => target.ilk === null && !target.savedBefore && reger.saved.get([target.said]) !== null)
+            .map(({ said }) => said),
+        complete: remaining.length === 0,
+        unaccepted: remaining,
+    };
+}
+/**
+ * Capture compact identities while dispatching each complete frame once, joining pending pulls and iterator return.
+ *
+ * @param protocol Borrowed dispatch owner; refusal diagnostics retain its actual decision detail.
+ * @param reger Borrowed store for saved markers observed before first raw credential dispatch.
+ * @param bytes Resident finite input, parsed incrementally before each dispatch.
+ * @param kvy This input's Kevery over the shared accepted-state domain.
+ * @returns Unique directly observed identities after parser EOF and joined source cleanup.
+ */
+function readImportTargets(protocol, reger, bytes, kvy) {
+    return call(function* () {
+        const controller = new AbortController();
+        const frames = parse(chunkBytes(bytes, { signal: controller.signal }));
+        const targets = new Map();
+        let pending;
+        // Handlers stop before this earlier resource joins reads and disposes the input iterator.
+        yield* ensure(function* () {
+            try {
+                if (pending) {
+                    try {
+                        yield* call(() => pending);
+                    }
+                    catch (error) {
+                        rethrowCleanupFailure(error, controller.signal);
+                    }
+                }
+            }
+            finally {
+                yield* call(() => frames.return());
+            }
+        });
+        try {
+            while (true) {
+                pending = frames.next();
+                let next;
+                try {
+                    next = yield* call(() => pending);
+                }
+                catch (error) {
+                    pending = undefined;
+                    throw error;
+                }
+                pending = undefined;
+                if (next.done)
+                    return [...targets.values()];
+                const serder = next.value.body;
+                if (!(serder instanceof SerderACDC) && !(serder instanceof SerderKERI)) {
+                    throw new TypeError("Credential import requires a KERI or ACDC message");
+                }
+                // Capture savedBefore exactly once, before dispatch can publish this credential's marker.
+                if (!targets.has(serder.said)) {
+                    const target = importTarget(serder, reger);
+                    if (target)
+                        targets.set(target.said, target);
+                }
+                const { decision } = yield* protocol.dispatch(next.value, {}, kvy);
+                if (decision && (decision.kind === "reject" || decision.kind === "drop")) {
+                    consoleLogger.warn("Credential import message refused", {
+                        said: serder.said,
+                        ilk: serder.ilk,
+                        pre: serder instanceof SerderKERI ? serder.pre : serder.issuer,
+                        reason: "reason" in decision ? decision.reason : decision.code,
+                        detail: "message" in decision ? decision.message : "detail" in decision ? decision.detail : undefined,
+                        cause: "cause" in decision ? decision.cause : undefined,
+                    });
+                }
+            }
+        }
+        finally {
+            controller.abort();
+        }
+    });
+}
+/**
+ * Project only coordinates for accepted records that this credential workflow observes.
+ *
+ * @param serder One directly imported message; embedded artifacts remain under their existing workflow owners.
+ * @param reger Credential store used only to record a raw credential's pre-dispatch saved marker.
+ * @returns Compact message identity, or null for messages handled without an importer completion predicate.
+ */
+function importTarget(serder, reger) {
+    const said = serder.said, ilk = serder.ilk;
+    if (serder instanceof SerderACDC) {
+        return ilk === null ? { ilk, said, savedBefore: reger.saved.get([said]) !== null } : null;
+    }
+    switch (ilk) {
+        case Ilks.icp:
+        case Ilks.dip:
+        case Ilks.rot:
+        case Ilks.drt:
+        case Ilks.ixn:
+        case Ilks.vcp:
+        case Ilks.vrt:
+        case Ilks.iss:
+        case Ilks.rev:
+        case Ilks.bis:
+        case Ilks.brv:
+            return { ilk, said, pre: serder.pre, sn: serder.sn };
+        case Ilks.exn:
+            return { ilk, said };
+        default:
+            return null;
+    }
+}
+/**
+ * Observe the normal accepted record without consulting direct-attempt decisions.
+ *
+ * @param target Input identity; raw storage and unrelated latest heads do not establish its acceptance.
+ * @param protocol Borrowed accepted KEL/exchange domain.
+ * @param reger Borrowed accepted credential/TEL domain.
+ * @returns Whether this exact message has its normal durable acceptance evidence.
+ */
+function importTargetAccepted(target, protocol, reger) {
+    switch (target.ilk) {
+        case null:
+            return reger.saved.get([target.said]) !== null;
+        case Ilks.icp:
+        case Ilks.dip:
+        case Ilks.rot:
+        case Ilks.drt:
+        case Ilks.ixn:
+            return target.pre !== null && target.sn !== null
+                && protocol.kvy.db.kels.getLast(target.pre, target.sn) === target.said;
+        case Ilks.vcp:
+        case Ilks.vrt:
+        case Ilks.iss:
+        case Ilks.rev:
+        case Ilks.bis:
+        case Ilks.brv:
+            return target.pre !== null && target.sn !== null && reger.tels.getOn(target.pre, target.sn)?.qb64 === target.said;
+        case Ilks.exn:
+            return protocol.kvy.db.exns.get([target.said]) !== null;
+    }
+}

package/esm/keri/npm/src/app/credentials/credential-proposals.js

@@ -0,0 +1,120 @@
+/** Read-only legacy credential proposal checks performed before member approval/signing. */
+import { concatBytes, Counter, Ilks, parseBytes, TraitDex, } from "cesr-ts";
+import { ValidationError } from "../../core/errors.js";
+import { Credentialer } from "../../vdr/credentialing.js";
+import { validateRegistryInception } from "../../vdr/eventing.js";
+import { validateCredentialRevocation } from "../../vdr/revoking.js";
+import { telAnchorMatches } from "../../vdr/tel-anchor.js";
+import { envelopeFromFrame } from "../protocol/parsering.js";
+import { resolveCachedSchema } from "./schema-resolving.js";
+/** Refuse a blank or conflicting local registry alias before signing its anchor. */
+export function validateRegistryName(reger, name, regk) {
+    if (!name.trim())
+        throw new ValidationError("Registry name is required.");
+    const existing = reger.regs.get(name);
+    if (existing && existing.registryKey !== regk) {
+        throw new ValidationError(`Registry name ${name} already identifies another registry.`);
+    }
+}
+/**
+ * Require known group KEL authority before adding a fresh anchor signature.
+ * A future predecessor stays pending. An accepted historical anchor can use the
+ * current keys only while no intervening establishment event has changed them;
+ * recorded approval instead reuses its original contribution.
+ */
+export function groupCredentialAnchorReady(hby, issuer, anchor) {
+    const kever = hby.db.getKever(issuer);
+    if (!kever)
+        return false;
+    if (kever.estOnly && !anchor.estive) {
+        throw new ValidationError("Establishment-only group requires an establishment anchor.");
+    }
+    const sn = anchor.sn;
+    if (sn === null || anchor.pre !== issuer)
+        throw new ValidationError("Invalid group anchor identity.");
+    if (sn > kever.sn + 1)
+        return false;
+    if (sn <= kever.sn) {
+        if (hby.db.kels.getLast(issuer, sn) !== anchor.said) {
+            throw new ValidationError("Group anchor conflicts with accepted KEL state.");
+        }
+        return kever.lastEst.s <= sn;
+    }
+    if (anchor.ked?.p !== kever.said) {
+        throw new ValidationError("Group anchor predecessor does not match accepted KEL state.");
+    }
+    return true;
+}
+/** Validate the signed VCP policy and its exact issuer anchor without accepting either event. */
+export function validateRegistryProposal(issuer, event, anchor) {
+    const inception = validateRegistryInception(event);
+    if (!inception.noBackers)
+        throw new ValidationError("Local registry authoring requires NoBackers policy.");
+    if (inception.issuer !== issuer)
+        throw new ValidationError("Registry inception issuer does not match its group.");
+    validateProposalAnchor(issuer, event, anchor, inception.estOnly);
+}
+/**
+ * Validate issuer/registry/credential/TEL bindings and the cached credential schema.
+ * Missing accepted registry or schema remains pending. Malformed business evidence
+ * is refused without changing KEL, TEL, wallet or alias state; storage faults propagate.
+ */
+export function validateCredentialIssueProposal(rgy, issuer, creder, event, anchor) {
+    if (event.ilk !== Ilks.iss) {
+        throw new ValidationError("Local credential issuance requires iss evidence in a NoBackers registry.");
+    }
+    if (!creder.verify() || !event.verify() || event.pre !== creder.said || event.sn !== 0 || creder.issuer !== issuer) {
+        throw new ValidationError("Credential issuance does not match its credential and group issuer.");
+    }
+    const regk = creder.regid;
+    if (!regk)
+        throw new ValidationError("Credential issuance is missing its registry identifier.");
+    const state = rgy.reger.states.get(regk);
+    if (!state)
+        return false;
+    if (state.ii !== issuer)
+        throw new ValidationError("Credential registry is controlled by another issuer.");
+    if (!(state.c ?? []).includes(TraitDex.NoBackers) || event.ked?.ri !== regk) {
+        throw new ValidationError("Local credential issuance registry or NoBackers policy mismatch.");
+    }
+    if (anchor)
+        validateProposalAnchor(issuer, event, anchor, (state.c ?? []).includes(TraitDex.EstOnly));
+    const prior = rgy.reger.tels.getOn(creder.said, 0);
+    if (prior && prior.qb64 !== event.said)
+        throw new ValidationError("Credential already has another issuance event.");
+    const schema = creder.schema;
+    if (typeof schema === "string" && !resolveCachedSchema(rgy.hby, schema))
+        return false;
+    new Credentialer(rgy.hby, { reger: rgy.reger, vry: rgy.vry }).validate(creder);
+    return true;
+}
+/** Require saved issuer/registry/issuance authority and the exact REV anchor before approving. */
+export function validateCredentialRevocationProposal(rgy, issuer, credentialSaid, event, anchor) {
+    if (event.pre !== credentialSaid)
+        throw new ValidationError("Revocation selector does not match its TEL event.");
+    if (!validateCredentialRevocation(rgy.reger, issuer, event))
+        return false;
+    const state = rgy.reger.states.get(rgy.reger.creds.get(credentialSaid).regid);
+    validateProposalAnchor(issuer, event, anchor, (state.c ?? []).includes(TraitDex.EstOnly));
+    return true;
+}
+/** Check the ACDC's actual CESR source triple, independently of the coordinating parent's signatures. */
+export function validateCredentialSource(creder, issuance, attachment, genus) {
+    const frames = parseBytes(concatBytes(Counter.makeGVC(genus), creder.raw, attachment));
+    if (frames.length !== 1)
+        throw new ValidationError("Credential source evidence must contain one credential.");
+    // Match ordinary ACDC dispatch and KERIpy: the last source triple is authoritative.
+    const source = envelopeFromFrame(frames[0]).lastSst;
+    if (!source || source.i.qb64 !== issuance.pre || source.s.num !== issuance.sner?.num
+        || source.d.qb64 !== issuance.said)
+        throw new ValidationError("Credential source seal does not match the proposed issuance.");
+}
+/** Compare the full TEL seal and enforce the registry's establishment-only anchor policy. */
+function validateProposalAnchor(issuer, event, anchor, estOnly) {
+    if (!telAnchorMatches(issuer, event, anchor)) {
+        throw new ValidationError("TEL proposal anchor does not match its event.");
+    }
+    if (estOnly && !anchor.estive) {
+        throw new ValidationError("Establishment-only registry requires an establishment anchor.");
+    }
+}

package/esm/keri/npm/src/app/credentials/credential-revoking.js

@@ -0,0 +1,165 @@
+/** Legacy NoBackers revocation, member fanout and explicit delivery of completed evidence. */
+import { Diger, Ilks, SerderKERI, TraitDex } from "cesr-ts";
+import { DatabaseOperationError, ValidationError } from "../../core/errors.js";
+import { CREDENTIAL_MAILBOX_TOPIC } from "../../core/mailbox/mailbox-topics.js";
+import { messagize } from "../../core/protocol-serialization.js";
+import { dgKey } from "../../db/core/keys.js";
+import { telAnchorMatches } from "../../vdr/tel-anchor.js";
+import { Organizer } from "../identity/organizing.js";
+import { groupMemberHasKey, isLocalGroupHab, localGroupMember } from "../multisig/group-members.js";
+import { MULTISIG_REV_ROUTE } from "../multisig/grouping.js";
+import { anchorGroupCredentialEvent, publishGroupVcProposal } from "./credential-workflows.js";
+/**
+ * Revoke once or resume the original event. Group issuers author a partial anchor,
+ * retain ordinary protocol evidence, then admit/fan out the exact coordination
+ * wrapper. This operation neither waits for peer approval nor delivers pending
+ * evidence to business recipients. The caller runs the host and owns its deadline.
+ */
+export function* revokeCredential(rgy, input, postman, options) {
+    const { hby, reger } = rgy;
+    const registry = rgy.registryByName(options.registryName);
+    if (!registry)
+        throw new ValidationError(`Registry ${options.registryName} not found.`);
+    const [creder] = reger.cloneCred(options.credentialSaid);
+    let event;
+    let decision;
+    let group;
+    if (isLocalGroupHab(hby, registry.hab)) {
+        event = registry.prepareRevocation(options.credentialSaid);
+        const retained = retainedAnchor(rgy, registry.hab.pre, event);
+        let anchor;
+        if (retained) {
+            anchor = {
+                serder: retained,
+                message: messagize(retained, { sigers: hby.db.sigs.get(dgKey(retained.pre, retained.said)) }),
+            };
+        }
+        else {
+            const estOnly = registry.estOnly || (reger.states.get(registry.regk)?.c ?? []).includes(TraitDex.EstOnly);
+            anchor = anchorGroupCredentialEvent(hby, registry.hab, event, estOnly);
+        }
+        decision = rgy.tvy.processEvent({
+            serder: event,
+            seqner: anchor.serder.sner,
+            saider: new Diger({ qb64: anchor.serder.said }),
+        });
+        rgy.processEscrows();
+        rgy.publication.track(event, anchor.serder);
+        group = {
+            route: MULTISIG_REV_ROUTE,
+            ...(yield* publishGroupVcProposal(hby, input, postman, registry.hab, {
+                route: MULTISIG_REV_ROUTE,
+                attrs: { gid: registry.hab.pre, said: options.credentialSaid },
+                embeds: { rev: event.raw, anc: anchor.message },
+            })),
+        };
+    }
+    else {
+        const revoked = registry.revoke(options.credentialSaid);
+        event = revoked.serder;
+        decision = revoked.decision;
+    }
+    const accepted = reger.tels.getOn(options.credentialSaid, 1)?.qb64 === event.said;
+    return {
+        creder,
+        said: options.credentialSaid,
+        tel: event.said,
+        status: accepted ? "accept" : decision.kind,
+        accepted,
+        publicationComplete: rgy.publication.complete(options.credentialSaid, 1),
+        deliveries: [],
+        ...(group ? { group } : {}),
+    };
+}
+/**
+ * Send only accepted, publication-complete REV evidence. Elect the lowest verified
+ * historical anchor signer for a group; another member returns no deliveries.
+ * Poster completion means local transport, not remote protocol acknowledgement.
+ * An explicit repeat may resend; there is no durable delivery ledger or retry worker.
+ */
+export function* deliverCredentialRevocation(rgy, postman, credentialSaid, recipients) {
+    const { hby, reger } = rgy;
+    const [creder] = reger.cloneCred(credentialSaid);
+    const accepted = reger.tels.getOn(credentialSaid, 1);
+    if (!accepted || !rgy.publication.complete(credentialSaid, 1))
+        return [];
+    const raw = reger.tvts.get(dgKey(credentialSaid, accepted.qb64));
+    if (!raw)
+        throw new DatabaseOperationError("Accepted revocation body is missing.");
+    // retainedAnchor checks the complete original TEL/issuer source relationship.
+    const event = new SerderKERI({ raw });
+    if (event.pre !== credentialSaid || event.said !== accepted.qb64 || event.ilk !== Ilks.rev || !event.verify()) {
+        throw new DatabaseOperationError("Accepted revocation identity is inconsistent.");
+    }
+    const issuer = creder.issuer;
+    const hab = hby.habs.get(issuer);
+    if (!hab)
+        throw new ValidationError("Revocation issuer is not a local habitat.");
+    let sender = hab;
+    if (isLocalGroupHab(hby, hab)) {
+        const anchor = retainedAnchor(rgy, issuer, event);
+        if (!anchor)
+            throw new DatabaseOperationError("Accepted revocation issuer source seal is missing.");
+        if (!groupAnchorLead(hby, hab, anchor))
+            return [];
+        sender = localGroupMember(hby, issuer);
+    }
+    const deliveries = [];
+    const messages = [
+        ...hby.db.clonePreIter(issuer),
+        ...reger.clonePreIter(creder.regid),
+        ...reger.clonePreIter(credentialSaid),
+    ];
+    for (const recipient of recipients) {
+        const dest = new Organizer(hby.db, hby.signator).resolveRecipient(recipient);
+        for (const msg of messages) {
+            const evt = postman.send({ src: sender.pre, dest, msg, topic: CREDENTIAL_MAILBOX_TOPIC }, { notify: true });
+            const outcome = yield* postman.wait(evt);
+            if (outcome.kin === "failed")
+                throw outcome.error;
+            deliveries.push(...outcome.deliveries);
+        }
+    }
+    return deliveries;
+}
+/** Resolve explicit destinations and the caller's choice to notify a disclosed issuee. */
+export function revocationRecipients(creder, explicit, includeIssuee) {
+    const recipients = includeIssuee && creder.issuee ? [creder.issuee, ...explicit] : [...explicit];
+    return [...new Set(recipients.filter(recipient => recipient.length > 0))];
+}
+/** Recover the original source coordinate without replacing a lost or contradictory anchor. */
+function retainedAnchor(rgy, issuer, event) {
+    const couple = rgy.reger.ancs.get(dgKey(event.pre, event.said));
+    if (!couple)
+        return null;
+    const anchor = rgy.hby.db.getEvtSerder(issuer, couple[1].qb64);
+    if (!anchor || anchor.sner?.num !== couple[0].num || !telAnchorMatches(issuer, event, anchor)) {
+        throw new DatabaseOperationError("Stored revocation issuer anchor is missing or inconsistent.");
+    }
+    return anchor;
+}
+/** Use accepted historical establishment keys, not the group's current keys after a later rotation. */
+function groupAnchorLead(hby, group, anchor) {
+    const { db } = hby;
+    if (db.kels.getLast(group.pre, anchor.sn) !== anchor.said)
+        return false;
+    let keys = [];
+    for (const [sn, said] of db.getKelItemIter(group.pre)) {
+        if (sn > anchor.sn)
+            break;
+        const event = db.getEvtSerder(group.pre, said);
+        if (!event)
+            throw new DatabaseOperationError("Accepted issuer event body is missing.");
+        if (event.estive)
+            keys = event.verfers;
+    }
+    let index = Infinity;
+    for (const signature of db.sigs.get(dgKey(group.pre, anchor.said))) {
+        if (keys[signature.index]?.verify(signature.raw, anchor.raw))
+            index = Math.min(index, signature.index);
+    }
+    const key = keys[index];
+    if (!key)
+        throw new DatabaseOperationError("Accepted revocation anchor has no verified signer.");
+    return groupMemberHasKey(db, localGroupMember(hby, group.pre).pre, key.qb64);
+}