keri-ts 1.0.0 → 2.0.0

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

@@ -0,0 +1,365 @@
+/**
+ * Credential registry and lifecycle workflow orchestration.
+ *
+ * CLI adapters parse inputs and render outputs. This module owns registry state,
+ * credential issuance/import/export,
+ * and multisig VC proposal coordination.
+ */
+import { concatBytes, Diger, NumberPrimitive, NumDex, Prefixer, TraitDex, } from "cesr-ts";
+import { ValidationError } from "../../core/errors.js";
+import { incept as inceptRegistryEvent, issue as issueEvent } from "../../core/protocol-vdr-eventing.js";
+import { RegistryRecord } from "../../core/records.js";
+import { Schemer } from "../../core/scheming.js";
+import { Credentialer, CredentialWallet, Registry, serializeCredential } from "../../vdr/credentialing.js";
+import { validateRegistryInception } from "../../vdr/eventing.js";
+import { credentialStreamMessages } from "../ipex/ipex-credentialing.js";
+import { groupSigningMembers, isLocalGroupHab, localGroupMember } from "../multisig/group-members.js";
+import { MULTISIG_ISS_ROUTE, MULTISIG_VCP_ROUTE, prepareMultisigVdrExn, } from "../multisig/grouping.js";
+import { validateCredentialIssueProposal, validateRegistryName, } from "./credential-proposals.js";
+import { admitAndSendGroupMessage, groupSendResult, prepareGroupMessage, remoteGroupMembers, } from "../multisig/multisig-messaging.js";
+/** Pin a JSON schema body into the local schema table. */
+export function pinSchemaBytes(hby, raw) {
+    const schemer = new Schemer({ raw });
+    hby.db.schema.pin(schemer.said, schemer);
+    return schemer.said;
+}
+/**
+ * Create a single-sig registry or propose a group registry inception.
+ *
+ * @param rgy Borrowed legacy registry/credential owner.
+ * @param input Borrowed byte intake; commits each exact local wrapper before peer delivery.
+ * @param postman Borrowed Poster; its delivery worker must run while this operation awaits outcomes.
+ * @param hab Local signing habitat; its state/store lifetime remains with the caller.
+ * @param options Registry name/configuration and optional group proposal usage.
+ * @returns Registry/proposal state and actual deliveries, with acceptance reported separately.
+ */
+export function* inceptCredentialRegistry(rgy, input, postman, hab, options) {
+    const { hby } = rgy;
+    validateRegistryName(rgy.reger, options.registryName);
+    if (isLocalGroupHab(hby, hab)) {
+        return yield* proposeGroupRegistryIncept(rgy, input, postman, hab, options);
+    }
+    const registry = rgy.makeRegistry(options.registryName, hab, {
+        estOnly: options.estOnly ?? false,
+    });
+    return {
+        publicationComplete: rgy.publication.complete(registry.regk),
+        name: options.registryName,
+        registry: registry.regk,
+        issuer: hab.pre,
+    };
+}
+/** Return locally known credential registry records. */
+export function credentialRegistryRecords(reger) {
+    const records = [];
+    for (const [keys, record] of reger.regs.getTopItemIter()) {
+        records.push({
+            name: keys[0],
+            registry: record.registryKey,
+            issuer: record.prefix,
+        });
+    }
+    return records;
+}
+/** Return current TEL status for one local registry name. */
+export function credentialRegistryStatus(rgy, registryName) {
+    const record = rgy.reger.regs.get(registryName);
+    if (!record?.registryKey) {
+        throw new ValidationError(`Registry ${registryName} not found.`);
+    }
+    const tever = rgy.tvy.tevers.get(record.registryKey);
+    return {
+        name: registryName,
+        registry: record.registryKey,
+        issuer: record.prefix,
+        state: tever?.state() ?? null,
+    };
+}
+/**
+ * Create and issue one registry-backed credential.
+ *
+ * @param rgy Borrowed registry/TEL/credential owner.
+ * @param input Borrowed byte intake; commits each exact local wrapper before peer delivery.
+ * @param postman Borrowed Poster; its delivery worker must run while this operation awaits outcomes.
+ * @param options Issuer registry, credential data/schema, and optional delivery/export choices.
+ * @returns Credential/TEL result with saved/accepted state distinct from delivered URLs.
+ */
+export function* createCredential(rgy, input, postman, options) {
+    const { hby, reger } = rgy;
+    const registry = requireRegistry(rgy, options.registryName);
+    const credentialer = new Credentialer(hby, {
+        reger,
+        vry: rgy.vry,
+    });
+    const creder = credentialer.create({
+        registry,
+        schema: options.schema,
+        recipient: options.recipient,
+        data: options.data,
+        edges: options.edges,
+        rules: options.rules,
+    });
+    const recipient = options.recipient ?? creder.issuee ?? "";
+    if (isLocalGroupHab(hby, registry.hab)) {
+        return yield* proposeGroupCredentialIssue(rgy, input, postman, registry, creder, recipient);
+    }
+    const result = credentialer.issue(registry, creder);
+    return {
+        creder,
+        recipient,
+        tel: result.tel.said,
+        publicationComplete: rgy.publication.complete(creder.said),
+        status: result.verifierDecision.kind,
+    };
+}
+/** List locally saved credentials through wallet indexes. */
+export function listCredentials(rgy, options) {
+    const { reger } = rgy;
+    const wallet = new CredentialWallet(reger);
+    const tvy = rgy.tvy;
+    return wallet.list({ issued: options.issued ?? false, aid: options.aid, schema: options.schema }).map((said) => {
+        const [creder] = reger.cloneCred(said);
+        const tever = creder.regid ? tvy.tevers.get(creder.regid) : null;
+        return {
+            said,
+            issuer: creder.issuer,
+            issuee: creder.issuee,
+            schema: typeof creder.schema === "string" ? creder.schema : null,
+            status: tever?.vcState(said)?.et ?? null,
+        };
+    });
+}
+/** Build a KERIpy-compatible credential export stream. */
+export function exportCredentialStream(hby, reger, credentialSaid, recipient) {
+    const [creder] = reger.cloneCred(credentialSaid);
+    const resolvedRecipient = recipient ?? creder.issuee ?? "";
+    return {
+        creder,
+        recipient: resolvedRecipient,
+        bytes: credentialStreamBytes(hby, reger, creder, resolvedRecipient),
+    };
+}
+/** Build a KERIpy-compatible credential stream for an already loaded credential. */
+export function credentialStreamBytes(hby, reger, creder, recipient) {
+    return concatBytes(...credentialStreamMessages(hby, reger, creder, recipient));
+}
+/** Author the required group anchor after all available business evidence has been validated. */
+export function anchorGroupCredentialEvent(hby, hab, event, estOnly) {
+    const data = [{ i: event.pre, s: event.snh, d: event.said }];
+    if (estOnly || hab.kever?.estOnly)
+        return hby.rotateGroupHab(hab.name, undefined, undefined, { data });
+    return hby.interactGroupHab(hab.name, undefined, { data });
+}
+/**
+ * Construct a group registry inception and anchored proposal, then await member delivery.
+ * Local TEL acceptance is reported separately from successful proposal transmission.
+ *
+ * @param rgy Borrowed registry owner and accepted state.
+ * @param input Borrowed byte intake; commits each exact local wrapper before peer delivery.
+ * @param postman Borrowed Poster; its delivery worker must run while this operation awaits outcomes.
+ * @param hab Group issuer habitat.
+ * @param options Registry name and establishment policy; local authoring always uses NoBackers.
+ * @returns Proposal route, registry identity, TEL status and completed target deliveries.
+ */
+function* proposeGroupRegistryIncept(rgy, input, postman, hab, options) {
+    const { hby, reger } = rgy;
+    const estOnly = options.estOnly ?? false;
+    const cnfg = [
+        TraitDex.NoBackers,
+        ...(estOnly ? [TraitDex.EstOnly] : []),
+    ];
+    const vcp = inceptRegistryEvent(hab.pre, { cnfg });
+    validateRegistryInception(vcp);
+    const anchor = anchorGroupCredentialEvent(hby, hab, vcp, estOnly);
+    const seal = sourceSeal(anchor.serder);
+    const decision = rgy.tvy.processEvent({
+        serder: vcp,
+        seqner: seal.seqner,
+        saider: seal.saider,
+    });
+    rgy.processEscrows();
+    const regk = requireSerderPrefix(vcp, "registry inception");
+    registerRegistry(rgy, options.registryName, hab, regk, { estOnly });
+    rgy.publication.track(vcp, anchor.serder);
+    const publication = yield* publishGroupVcProposal(hby, input, postman, hab, {
+        route: MULTISIG_VCP_ROUTE,
+        attrs: { gid: hab.pre, usage: options.usage ?? options.registryName },
+        embeds: { vcp: vcp.raw, anc: anchor.message },
+    });
+    return {
+        publicationComplete: rgy.publication.complete(regk),
+        name: options.registryName,
+        registry: regk,
+        issuer: hab.pre,
+        group: {
+            route: MULTISIG_VCP_ROUTE,
+            status: decision.kind,
+            accepted: telAccepted(reger, regk, 0, requireSerderSaid(vcp, "registry inception")),
+            ...publication,
+        },
+    };
+}
+/**
+ * Prepare group issuance evidence and publish it to remote signing members.
+ * Return protocol status separately from transport delivery; peer signature
+ * collection may still be incomplete.
+ *
+ * @param rgy Borrowed registry and credential verification owner.
+ * @param input Borrowed byte intake; commits each exact local wrapper before peer delivery.
+ * @param postman Borrowed Poster; its delivery worker must run while this operation awaits outcomes.
+ * @param registry Group issuer registry to anchor issuance.
+ * @param creder Constructed credential to validate and bind to the TEL issue event.
+ * @param recipient Resolved issuee retained for the caller's subsequent export or delivery.
+ * @returns Credential/TEL decisions, saved state and completed member deliveries.
+ */
+function* proposeGroupCredentialIssue(rgy, input, postman, registry, creder, recipient) {
+    const { hby, reger } = rgy;
+    const regk = requireRegistryKey(registry);
+    const iss = issueEvent(requireCredentialSaid(creder), regk);
+    if (!validateCredentialIssueProposal(rgy, registry.hab.pre, creder, iss)) {
+        throw new ValidationError("Credential issuance is missing accepted registry or schema evidence.");
+    }
+    const estOnly = registry.estOnly || (reger.states.get(regk)?.c ?? []).includes(TraitDex.EstOnly);
+    const anchor = anchorGroupCredentialEvent(hby, registry.hab, iss, estOnly);
+    const seal = sourceSeal(anchor.serder);
+    const telDecision = rgy.tvy.processEvent({
+        serder: iss,
+        seqner: seal.seqner,
+        saider: seal.saider,
+    });
+    rgy.processEscrows();
+    const credentialSeal = telCredentialSeal(iss);
+    const verifierDecision = rgy.vry.processCredential({
+        creder,
+        prefixer: credentialSeal.prefixer,
+        seqner: credentialSeal.seqner,
+        saider: credentialSeal.saider,
+    });
+    if (verifierDecision.kind === "accept") {
+        reger.ccrd.pin(requireCredentialSaid(creder), creder);
+    }
+    rgy.vry.processEscrows();
+    rgy.publication.track(iss, anchor.serder);
+    const publication = yield* publishGroupVcProposal(hby, input, postman, registry.hab, {
+        route: MULTISIG_ISS_ROUTE,
+        attrs: { gid: registry.hab.pre },
+        embeds: {
+            acdc: serializeCredential(creder, credentialSeal.prefixer, credentialSeal.seqner, credentialSeal.saider),
+            iss: iss.raw,
+            anc: anchor.message,
+        },
+    });
+    return {
+        creder,
+        recipient,
+        tel: iss.said,
+        publicationComplete: rgy.publication.complete(creder.said),
+        status: verifierDecision.kind,
+        group: {
+            route: MULTISIG_ISS_ROUTE,
+            telStatus: telDecision.kind,
+            saved: credentialSaved(reger, creder),
+            ...publication,
+        },
+    };
+}
+/**
+ * Send one signed proposal per remote signing member and await each delivery.
+ * Local members are skipped; a failed outcome throws before reporting success.
+ *
+ * @param hby Borrowed local identities and accepted-state stores.
+ * @param postman Borrowed Poster; its delivery worker must run while this operation awaits outcomes.
+ * @param groupHab Group issuer habitat whose remote signing members receive the proposal.
+ * @param proposal Registry, issuance or revocation route with its required named evidence.
+ * @returns Stable proposal/wrapper identities and successful target URLs after concrete Poster completion.
+ */
+export function* publishGroupVcProposal(hby, input, postman, groupHab, proposal) {
+    const member = localGroupMember(hby, groupHab.pre);
+    const outcomes = [];
+    for (const recipient of remoteGroupMembers(hby, member, groupSigningMembers(hby, groupHab.pre))) {
+        const prepared = prepareMultisigVdrExn(member.pre, proposal, { recipient });
+        const signed = yield* prepareGroupMessage(input.protocol.exc, member, recipient, prepared);
+        outcomes.push(yield* admitAndSendGroupMessage(input, postman, signed));
+    }
+    return groupSendResult(outcomes);
+}
+function registerRegistry(rgy, name, hab, regk, options) {
+    rgy.reger.registries.add(regk);
+    rgy.reger.regs.pin(name, new RegistryRecord({
+        registryKey: regk,
+        prefix: hab.pre,
+    }));
+    if (!rgy.registries.has(name)) {
+        rgy.registries.set(name, new Registry({
+            publication: rgy.publication,
+            name,
+            hab,
+            reger: rgy.reger,
+            tvy: rgy.tvy,
+            cues: rgy.cues,
+            regk,
+            estOnly: options.estOnly,
+        }));
+    }
+}
+function sourceSeal(serder) {
+    return {
+        prefixer: new Prefixer({ qb64: requireSerderPrefix(serder, "anchor event") }),
+        seqner: ordinal(serder.sn ?? 0),
+        saider: new Diger({ qb64: requireSerderSaid(serder, "anchor event") }),
+    };
+}
+function telCredentialSeal(serder) {
+    return {
+        prefixer: new Prefixer({ qb64: requireSerderPrefix(serder, "credential TEL event") }),
+        seqner: ordinal(serder.sn ?? 0),
+        saider: new Diger({ qb64: requireSerderSaid(serder, "credential TEL event") }),
+    };
+}
+function ordinal(num) {
+    const raw = new Uint8Array(16);
+    let value = BigInt(num);
+    for (let i = raw.length - 1; i >= 0; i--) {
+        raw[i] = Number(value & 0xffn);
+        value >>= 8n;
+    }
+    return new NumberPrimitive({ code: NumDex.Huge, raw });
+}
+function requireRegistry(rgy, name) {
+    const registry = rgy.registryByName(name);
+    if (!registry) {
+        throw new ValidationError(`Registry ${name} not found.`);
+    }
+    return registry;
+}
+function requireRegistryKey(registry) {
+    if (!registry.regk) {
+        throw new ValidationError(`Registry ${registry.name} has not been incepted.`);
+    }
+    return registry.regk;
+}
+function requireCredentialSaid(creder) {
+    if (!creder.said) {
+        throw new ValidationError("Credential is missing SAID.");
+    }
+    return creder.said;
+}
+function credentialSaved(reger, creder) {
+    const said = requireCredentialSaid(creder);
+    return reger.saved.get([said]) !== null || reger.ccrd.get(said) !== null;
+}
+function requireSerderPrefix(serder, label) {
+    if (!serder.pre) {
+        throw new ValidationError(`${label} is missing prefix.`);
+    }
+    return serder.pre;
+}
+function requireSerderSaid(serder, label) {
+    if (!serder.said) {
+        throw new ValidationError(`${label} is missing SAID.`);
+    }
+    return serder.said;
+}
+function telAccepted(reger, pre, sn, eventSaid) {
+    return reger.tels.getOn(pre, sn)?.qb64 === eventSaid;
+}

package/esm/keri/npm/src/app/credentials/tel-publishing.js

@@ -0,0 +1,27 @@
+import { ValidationError } from "../../core/errors.js";
+import { sendWitnessMessage } from "../witness/receipt-client.js";
+/**
+ * Advance one captured set of protocol escrows. Receipt collection includes
+ * fanout; a crash before its commit repeats that ordinary finite operation.
+ * Dissemination replays accepted TEL evidence to the anchor's historical witness
+ * cohort and commits ctel only after every local transmission finished. Failure
+ * retains the corresponding escrow for explicit resume, without an outbox.
+ */
+export function* publishPendingTel(hby, publication, receiptor, http, clock) {
+    publication.advance();
+    for (const target of publication.pendingReceipts()) {
+        yield* receiptor.receipt(target.issuer, { sn: target.anchorSn, allowTcp: true });
+        publication.receipted(target);
+    }
+    for (const target of publication.pendingPublications()) {
+        const hab = hby.habs.get(target.issuer);
+        if (!hab)
+            throw new ValidationError(`Missing local TEL issuer ${target.issuer}.`);
+        const diger = publication.reger.tels.getOn(target.pre, target.sn);
+        const message = publication.reger.cloneTvt(target.pre, diger);
+        for (const witness of target.witnesses) {
+            yield* sendWitnessMessage(hab, witness, message, http, clock, null);
+        }
+        publication.published(target);
+    }
+}

package/esm/keri/npm/src/app/{verifying.js → credentials/verifying.js}

@@ -10,12 +10,13 @@
  *   flow; durable corruption and unsupported `DI2I` still fail explicitly
  */
 import { Dater, Ilks, Saider, } from "cesr-ts";
-import { Deck } from "../core/deck.js";
-import { ValidationError } from "../core/errors.js";
-import { encodeDateTimeToDater, makeNowIso8601 } from "../time/mod.js";
+import { Deck } from "../../core/deck.js";
+import { ValidationError } from "../../core/errors.js";
+import { consoleLogger } from "../../core/logger.js";
+import { encodeDateTimeToDater, makeNowIso8601 } from "../../time/mod.js";
 import { resolveCachedSchema } from "./schema-resolving.js";
 /**
- * Concrete credential verifier supplied directly to `Reactor`.
+ * Concrete credential verifier supplied to the shared `ProtocolProcessor`.
  *
  * The verifier owns only credential validation/indexing and its own VDR escrows.
  * TEL processing remains delegated to `Tevery`, and webhook/application policy
@@ -125,11 +126,14 @@ export class Verifier {
             schemer.verify(creder.raw);
         }
         catch (error) {
+            if (!(error instanceof ValidationError))
+                throw error;
             return {
                 kind: "reject",
                 reason: "invalidSchema",
                 said,
                 detail: error instanceof Error ? error.message : String(error),
+                cause: error,
             };
         }
         const edges = normalizedEdges(creder.edge);
@@ -160,11 +164,14 @@ export class Verifier {
                     chainState = this.verifyChain(node.n, op, issuer);
                 }
                 catch (error) {
+                    if (!(error instanceof ValidationError))
+                        throw error;
                     return {
                         kind: "reject",
                         reason: "unsupportedChainOperator",
                         said,
                         detail: error instanceof Error ? error.message : String(error),
+                        cause: error,
                     };
                 }
                 if (!chainState) {
@@ -273,6 +280,16 @@ export class Verifier {
         const tever = regk ? teverFrom(this.tevers.get(regk)) : null;
         return tever?.vcState(nodeSaid) ?? null;
     }
+    /**
+     * Retry one dependency family and report terminal removals after they succeed.
+     *
+     * Acceptance and migration to another family are ordinary progress, not ejection.
+     * Storage failures propagate with the original evidence still owned by its escrow.
+     *
+     * @param db Pending credential identities and their original admission timestamps.
+     * @param expectedReason Dependency family whose membership this pass owns.
+     * @param timeoutMs Maximum pending age in milliseconds; equality remains eligible.
+     */
     processEscrow(db, expectedReason, timeoutMs) {
         for (const [keys, dater] of db.getTopItemIter()) {
             const said = keys[0];
@@ -280,14 +297,32 @@ export class Verifier {
                 continue;
             }
             if (Date.now() - new Date(dater.dts).getTime() > timeoutMs) {
-                db.rem([said]);
+                if (db.rem([said])) {
+                    consoleLogger.warn("Verifier ejected credential escrow", {
+                        family: expectedReason,
+                        said,
+                        reason: "expired",
+                        detail: `Credential dependency remained unresolved beyond ${timeoutMs} ms.`,
+                    });
+                }
                 continue;
             }
             const [creder, prefixer, seqner, saider] = this.reger.cloneCred(said);
             // Remote validation outcomes are typed; thrown failures retain their exact identity and escrow owner.
             const decision = this.processCredential({ creder, prefixer, seqner, saider });
             if (decision.kind === "accept" || decision.kind === "reject") {
-                db.rem([said]);
+                const removed = db.rem([said]);
+                if (removed && decision.kind === "reject") {
+                    consoleLogger.warn("Verifier ejected credential escrow", {
+                        family: expectedReason,
+                        said,
+                        issuer: creder.issuer,
+                        registry: creder.regid,
+                        reason: decision.reason,
+                        detail: decision.detail,
+                        cause: decision.cause,
+                    });
+                }
                 continue;
             }
             if (decision.reason !== expectedReason) {