@interop/wallet-core 0.23.1 → 0.25.0

package/dist/resourceLog/append.d.ts

@@ -0,0 +1,103 @@
+import { type ResourceLogEntry, type ResourceLogStore } from '@interop/was-client/log';
+import type { ResourceLogController } from './controller.js';
+import { type ResourceLogSigner } from './entry.js';
+import type { ResourceLogPinStore } from './pin.js';
+import { type VerifiedResourceLog } from './verify.js';
+/**
+ * Reads and fully verifies a log through the store seam, advancing the
+ * chain-head pin. Resolves `null` when the log resource does not exist yet
+ * (the pre-genesis state). The one read entry point every consumer -- a
+ * login-time roster read, a pre-append verification, a first-contact
+ * bootstrap -- goes through, so the pin rules cannot be bypassed by reading
+ * around them.
+ *
+ * @param options {object}
+ * @param options.store {ResourceLogStore}   the log's transport seam
+ * @param options.controller {ResourceLogController}   the verified controller
+ *   view
+ * @param options.expectedMethod {string}   the format identifier expected
+ *   (also confirming any `history` dispatch hint the caller followed)
+ * @param options.pinStore {ResourceLogPinStore}   this client's pin for this
+ *   log
+ * @returns {Promise<{ verified: VerifiedResourceLog; etag?: string } | null>}
+ */
+export declare function readResourceLog({ store, controller, expectedMethod, pinStore }: {
+    store: ResourceLogStore;
+    controller: ResourceLogController;
+    expectedMethod: string;
+    pinStore: ResourceLogPinStore;
+}): Promise<{
+    verified: VerifiedResourceLog;
+    etag?: string;
+} | null>;
+/**
+ * Appends one state change: verify, build against the verified head, CAS,
+ * rebase-and-retry on conflict, confirm by read-back. `buildState` is the
+ * rebase hook -- it is called with the current verified log on every attempt
+ * and returns the full next state built on THAT head's state (or `null` to
+ * signal the change is already present, making a re-run converge instead of
+ * duplicating an entry). Refuses a log whose verified head is a terminal
+ * handover entry ({@link ResourceLogClosedError}).
+ *
+ * @param options {object}
+ * @param options.store {ResourceLogStore}
+ * @param options.controller {ResourceLogController}
+ * @param options.expectedMethod {string}
+ * @param options.pinStore {ResourceLogPinStore}
+ * @param options.signer {ResourceLogSigner}
+ * @param options.buildState {function}   `(verified) => state | null` -- the
+ *   full next state rebased on the verified head, or `null` when the head
+ *   already carries the change
+ * @param [options.versionTime] {string}   RFC3339 UTC; defaults to now
+ * @param [options.maxAttempts] {number}   CAS attempts before giving up
+ *   (default 3)
+ * @returns {Promise<VerifiedResourceLog>}   the read-back, re-verified log
+ *   (whether or not this call appended)
+ */
+export declare function appendResourceLog({ store, controller, expectedMethod, pinStore, signer, buildState, versionTime, maxAttempts }: {
+    store: ResourceLogStore;
+    controller: ResourceLogController;
+    expectedMethod: string;
+    pinStore: ResourceLogPinStore;
+    signer: ResourceLogSigner;
+    buildState: (verified: VerifiedResourceLog) => Promise<ResourceLogEntry['state'] | null> | ResourceLogEntry['state'] | null;
+    versionTime?: string;
+    maxAttempts?: number;
+}): Promise<VerifiedResourceLog>;
+/**
+ * Creates a log with its genesis entry, guarded create-if-absent, and
+ * confirms by read-back. Losing the create race to a concurrent provisioner
+ * adopts the winner's log (the create is CAS, never clobbering): the served
+ * log is verified and pinned, and the caller reconciles its intended state
+ * through an ordinary {@link appendResourceLog}. First contact is where the
+ * pin is established, so the pin store is written either way.
+ *
+ * @param options {object}
+ * @param options.store {ResourceLogStore}
+ * @param options.controller {ResourceLogController}
+ * @param options.method {string}   the format identifier to declare
+ * @param options.pinStore {ResourceLogPinStore}
+ * @param options.signer {ResourceLogSigner}
+ * @param options.state {ResourceLogEntry['state']}   the full initial state
+ * @param [options.previousLog] {object}   handover successors only
+ * @param [options.versionTime] {string}   RFC3339 UTC; defaults to now
+ * @returns {Promise<{ verified: VerifiedResourceLog; created: boolean }>}
+ *   the verified log as it now stands, and whether this call created it
+ */
+export declare function createResourceLog({ store, controller, method, pinStore, signer, state, previousLog, versionTime }: {
+    store: ResourceLogStore;
+    controller: ResourceLogController;
+    method: string;
+    pinStore: ResourceLogPinStore;
+    signer: ResourceLogSigner;
+    state: ResourceLogEntry['state'];
+    previousLog?: {
+        scid: string;
+        head: string;
+    };
+    versionTime?: string;
+}): Promise<{
+    verified: VerifiedResourceLog;
+    created: boolean;
+}>;
+//# sourceMappingURL=append.d.ts.map

package/dist/resourceLog/append.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"append.d.ts","sourceRoot":"","sources":["../../src/resourceLog/append.ts"],"names":[],"mappings":"AAeA,OAAO,EAEL,KAAK,gBAAgB,EACrB,KAAK,gBAAgB,EACtB,MAAM,yBAAyB,CAAA;AAChC,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,iBAAiB,CAAA;AAE5D,OAAO,EAGL,KAAK,iBAAiB,EACvB,MAAM,YAAY,CAAA;AACnB,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,UAAU,CAAA;AACnD,OAAO,EAAqB,KAAK,mBAAmB,EAAE,MAAM,aAAa,CAAA;AAEzE;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAsB,eAAe,CAAC,EACpC,KAAK,EACL,UAAU,EACV,cAAc,EACd,QAAQ,EACT,EAAE;IACD,KAAK,EAAE,gBAAgB,CAAA;IACvB,UAAU,EAAE,qBAAqB,CAAA;IACjC,cAAc,EAAE,MAAM,CAAA;IACtB,QAAQ,EAAE,mBAAmB,CAAA;CAC9B,GAAG,OAAO,CAAC;IAAE,QAAQ,EAAE,mBAAmB,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAAC,CAcnE;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAsB,iBAAiB,CAAC,EACtC,KAAK,EACL,UAAU,EACV,cAAc,EACd,QAAQ,EACR,MAAM,EACN,UAAU,EACV,WAAW,EACX,WAAe,EAChB,EAAE;IACD,KAAK,EAAE,gBAAgB,CAAA;IACvB,UAAU,EAAE,qBAAqB,CAAA;IACjC,cAAc,EAAE,MAAM,CAAA;IACtB,QAAQ,EAAE,mBAAmB,CAAA;IAC7B,MAAM,EAAE,iBAAiB,CAAA;IACzB,UAAU,EAAE,CACV,QAAQ,EAAE,mBAAmB,KAE7B,OAAO,CAAC,gBAAgB,CAAC,OAAO,CAAC,GAAG,IAAI,CAAC,GAAG,gBAAgB,CAAC,OAAO,CAAC,GAAG,IAAI,CAAA;IAC9E,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,WAAW,CAAC,EAAE,MAAM,CAAA;CACrB,GAAG,OAAO,CAAC,mBAAmB,CAAC,CA+D/B;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAsB,iBAAiB,CAAC,EACtC,KAAK,EACL,UAAU,EACV,MAAM,EACN,QAAQ,EACR,MAAM,EACN,KAAK,EACL,WAAW,EACX,WAAW,EACZ,EAAE;IACD,KAAK,EAAE,gBAAgB,CAAA;IACvB,UAAU,EAAE,qBAAqB,CAAA;IACjC,MAAM,EAAE,MAAM,CAAA;IACd,QAAQ,EAAE,mBAAmB,CAAA;IAC7B,MAAM,EAAE,iBAAiB,CAAA;IACzB,KAAK,EAAE,gBAAgB,CAAC,OAAO,CAAC,CAAA;IAChC,WAAW,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAA;IAC5C,WAAW,CAAC,EAAE,MAAM,CAAA;CACrB,GAAG,OAAO,CAAC;IAAE,QAAQ,EAAE,mBAAmB,CAAC;IAAC,OAAO,EAAE,OAAO,CAAA;CAAE,CAAC,CAmC/D"}

package/dist/resourceLog/append.js

@@ -0,0 +1,190 @@
+/*!
+ * Copyright (c) 2026 Interop Alliance. All rights reserved.
+ */
+/**
+ * The append path (App Connect spec `#log-append`): read the full log and
+ * verify it (an entry is never built on an unverified head), build the new
+ * entry against the verified head anchored at the writer's current verified
+ * controller head, write compare-and-swapped on the read's validator, and on
+ * conflict re-read, re-verify, rebase, retry. A write acknowledgement is a
+ * promise, not a fact: every append is confirmed by reading the log back and
+ * re-verifying the extended history before the append -- or any ceremony step
+ * gated on it -- is treated as durable. The chain-head pin advances on every
+ * successful verification along the way, and only ever forward.
+ */
+import { PreconditionFailedError } from '@interop/was-client';
+import { confirmAppend } from '@interop/was-client/log';
+import { ResourceLogClosedError } from './errors.js';
+import { buildResourceLogEntry, buildResourceLogGenesis } from './entry.js';
+import { verifyResourceLog } from './verify.js';
+/**
+ * Reads and fully verifies a log through the store seam, advancing the
+ * chain-head pin. Resolves `null` when the log resource does not exist yet
+ * (the pre-genesis state). The one read entry point every consumer -- a
+ * login-time roster read, a pre-append verification, a first-contact
+ * bootstrap -- goes through, so the pin rules cannot be bypassed by reading
+ * around them.
+ *
+ * @param options {object}
+ * @param options.store {ResourceLogStore}   the log's transport seam
+ * @param options.controller {ResourceLogController}   the verified controller
+ *   view
+ * @param options.expectedMethod {string}   the format identifier expected
+ *   (also confirming any `history` dispatch hint the caller followed)
+ * @param options.pinStore {ResourceLogPinStore}   this client's pin for this
+ *   log
+ * @returns {Promise<{ verified: VerifiedResourceLog; etag?: string } | null>}
+ */
+export async function readResourceLog({ store, controller, expectedMethod, pinStore }) {
+    const current = await store.read();
+    if (current === null) {
+        return null;
+    }
+    const pin = await pinStore.read();
+    const verified = await verifyResourceLog({
+        entries: current.entries,
+        controller,
+        expectedMethod,
+        pin
+    });
+    await pinStore.write(verified.pin);
+    return { verified, etag: current.etag };
+}
+/**
+ * Appends one state change: verify, build against the verified head, CAS,
+ * rebase-and-retry on conflict, confirm by read-back. `buildState` is the
+ * rebase hook -- it is called with the current verified log on every attempt
+ * and returns the full next state built on THAT head's state (or `null` to
+ * signal the change is already present, making a re-run converge instead of
+ * duplicating an entry). Refuses a log whose verified head is a terminal
+ * handover entry ({@link ResourceLogClosedError}).
+ *
+ * @param options {object}
+ * @param options.store {ResourceLogStore}
+ * @param options.controller {ResourceLogController}
+ * @param options.expectedMethod {string}
+ * @param options.pinStore {ResourceLogPinStore}
+ * @param options.signer {ResourceLogSigner}
+ * @param options.buildState {function}   `(verified) => state | null` -- the
+ *   full next state rebased on the verified head, or `null` when the head
+ *   already carries the change
+ * @param [options.versionTime] {string}   RFC3339 UTC; defaults to now
+ * @param [options.maxAttempts] {number}   CAS attempts before giving up
+ *   (default 3)
+ * @returns {Promise<VerifiedResourceLog>}   the read-back, re-verified log
+ *   (whether or not this call appended)
+ */
+export async function appendResourceLog({ store, controller, expectedMethod, pinStore, signer, buildState, versionTime, maxAttempts = 3 }) {
+    let lastConflict;
+    for (let attempt = 0; attempt < maxAttempts; attempt++) {
+        const current = await readResourceLog({
+            store,
+            controller,
+            expectedMethod,
+            pinStore
+        });
+        if (current === null) {
+            throw new Error('Cannot append to the resource log: the log does not exist yet ' +
+                '(create it with its genesis entry first).');
+        }
+        const { verified, etag } = current;
+        if (verified.terminal) {
+            throw new ResourceLogClosedError({ nextLog: verified.terminal });
+        }
+        if (etag === undefined) {
+            throw new Error('Cannot append to the resource log: the backend returned no ' +
+                'validator, and the profile forbids an unconditional write.');
+        }
+        const state = await buildState(verified);
+        if (state === null) {
+            // The head already carries the change -- a torn earlier run landed it,
+            // or a concurrent writer did. Converged.
+            return verified;
+        }
+        const entry = await buildResourceLogEntry({
+            head: verified.head,
+            state,
+            controller,
+            signer,
+            versionTime
+        });
+        try {
+            await store.append(entry, { ifMatch: etag });
+        }
+        catch (err) {
+            if (err instanceof PreconditionFailedError) {
+                // A concurrent append won the CAS: re-read, re-verify, rebase, retry.
+                lastConflict = err;
+                continue;
+            }
+            throw err;
+        }
+        const readBack = await confirmAppend({ store, entry });
+        const confirmed = await verifyResourceLog({
+            entries: readBack.entries,
+            controller,
+            expectedMethod,
+            pin: await pinStore.read()
+        });
+        await pinStore.write(confirmed.pin);
+        return confirmed;
+    }
+    throw new Error(`Appending to the resource log lost the compare-and-swap race ` +
+        `${maxAttempts} times in a row.`, { cause: lastConflict });
+}
+/**
+ * Creates a log with its genesis entry, guarded create-if-absent, and
+ * confirms by read-back. Losing the create race to a concurrent provisioner
+ * adopts the winner's log (the create is CAS, never clobbering): the served
+ * log is verified and pinned, and the caller reconciles its intended state
+ * through an ordinary {@link appendResourceLog}. First contact is where the
+ * pin is established, so the pin store is written either way.
+ *
+ * @param options {object}
+ * @param options.store {ResourceLogStore}
+ * @param options.controller {ResourceLogController}
+ * @param options.method {string}   the format identifier to declare
+ * @param options.pinStore {ResourceLogPinStore}
+ * @param options.signer {ResourceLogSigner}
+ * @param options.state {ResourceLogEntry['state']}   the full initial state
+ * @param [options.previousLog] {object}   handover successors only
+ * @param [options.versionTime] {string}   RFC3339 UTC; defaults to now
+ * @returns {Promise<{ verified: VerifiedResourceLog; created: boolean }>}
+ *   the verified log as it now stands, and whether this call created it
+ */
+export async function createResourceLog({ store, controller, method, pinStore, signer, state, previousLog, versionTime }) {
+    const genesis = await buildResourceLogGenesis({
+        state,
+        method,
+        controller,
+        signer,
+        previousLog,
+        versionTime
+    });
+    let created = true;
+    try {
+        await store.create(genesis);
+    }
+    catch (err) {
+        if (!(err instanceof PreconditionFailedError)) {
+            throw err;
+        }
+        created = false;
+    }
+    const current = created
+        ? await confirmAppend({ store, entry: genesis })
+        : await store.read();
+    if (current === null) {
+        throw new Error('The resource log create lost its guarded-create race, but no log ' +
+            'was served on re-read.');
+    }
+    const verified = await verifyResourceLog({
+        entries: current.entries,
+        controller,
+        expectedMethod: method,
+        pin: await pinStore.read()
+    });
+    await pinStore.write(verified.pin);
+    return { verified, created };
+}
+//# sourceMappingURL=append.js.map

package/dist/resourceLog/append.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"append.js","sourceRoot":"","sources":["../../src/resourceLog/append.ts"],"names":[],"mappings":"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"}

package/dist/resourceLog/controller.d.ts

@@ -0,0 +1,57 @@
+/*!
+ * Copyright (c) 2026 Interop Alliance. All rights reserved.
+ */
+/**
+ * The controller-document view a resource-log verifier authorizes against:
+ * the profile's root of authority, resolved and verified by the reader
+ * independently of the host serving the log. The interface is the seam --
+ * verification consumes only the account DID, the ordered controller-log
+ * version list, and per-version `assertionMethod` membership -- and the
+ * did:webvh adapter builds it from an already-verified account log (the
+ * `verifyAccountLog` output), answering anchored-version lookups from that
+ * verified history rather than from any wire fetch. Handing the verifier a
+ * view instead of a resolver is what enforces the profile's rule that
+ * controller-document material never comes from the channel the log came
+ * from.
+ */
+import { type DIDLog } from '@interop/did-method-webvh';
+/**
+ * What log verification consumes of the independently verified controller
+ * document: the DID the entry proofs must sign under, the verified controller
+ * log's `versionId` list in order (empty for an unversioned static
+ * controller, degrading every anchor rule to current-document verification),
+ * and the set of `assertionMethod` key multibases at a given version --
+ * membership there is the whole authorization rule, so `keyAgreement`-only
+ * recovery keys and `authentication`-only convenience keys are excluded
+ * structurally.
+ */
+export interface ResourceLogController {
+    did: string;
+    versionIds: string[];
+    /**
+     * Resolves the `assertionMethod` public-key multibases at a controller-log
+     * version (`undefined`: the current document, the unversioned-controller
+     * degradation).
+     *
+     * @param [versionId] {string}
+     * @returns {Promise<Set<string>>}
+     */
+    assertionKeysAt(versionId?: string): Promise<Set<string>>;
+}
+/**
+ * Builds the controller view over an already-verified did:webvh account log
+ * (the `verifyAccountLog` output -- callers never hand this a log they have
+ * not verified against the account pointer). Anchored-version lookups
+ * re-resolve the held log at that version and are memoized: controller logs
+ * are tens of entries and anchors cluster on few versions.
+ *
+ * @param options {object}
+ * @param options.did {string}   the account's did:webvh, as verified
+ * @param options.log {DIDLog}   the verified account log
+ * @returns {ResourceLogController}
+ */
+export declare function webvhResourceLogController({ did, log }: {
+    did: string;
+    log: DIDLog;
+}): ResourceLogController;
+//# sourceMappingURL=controller.d.ts.map

package/dist/resourceLog/controller.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"controller.d.ts","sourceRoot":"","sources":["../../src/resourceLog/controller.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH;;;;;;;;;;;;GAYG;AACH,OAAO,EAAqB,KAAK,MAAM,EAAE,MAAM,2BAA2B,CAAA;AAG1E;;;;;;;;;GASG;AACH,MAAM,WAAW,qBAAqB;IACpC,GAAG,EAAE,MAAM,CAAA;IACX,UAAU,EAAE,MAAM,EAAE,CAAA;IACpB;;;;;;;OAOG;IACH,eAAe,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,CAAA;CAC1D;AAmCD;;;;;;;;;;;GAWG;AACH,wBAAgB,0BAA0B,CAAC,EACzC,GAAG,EACH,GAAG,EACJ,EAAE;IACD,GAAG,EAAE,MAAM,CAAA;IACX,GAAG,EAAE,MAAM,CAAA;CACZ,GAAG,qBAAqB,CAkCxB"}

package/dist/resourceLog/controller.js

@@ -0,0 +1,81 @@
+/*!
+ * Copyright (c) 2026 Interop Alliance. All rights reserved.
+ */
+/**
+ * The controller-document view a resource-log verifier authorizes against:
+ * the profile's root of authority, resolved and verified by the reader
+ * independently of the host serving the log. The interface is the seam --
+ * verification consumes only the account DID, the ordered controller-log
+ * version list, and per-version `assertionMethod` membership -- and the
+ * did:webvh adapter builds it from an already-verified account log (the
+ * `verifyAccountLog` output), answering anchored-version lookups from that
+ * verified history rather than from any wire fetch. Handing the verifier a
+ * view instead of a resolver is what enforces the profile's rule that
+ * controller-document material never comes from the channel the log came
+ * from.
+ */
+import { resolveDIDFromLog } from '@interop/did-method-webvh';
+import { ResourceLogIntegrityError } from './errors.js';
+/**
+ * Collects a document's `assertionMethod` key multibases: embedded
+ * verification methods verbatim, string references resolved against
+ * `verificationMethod`.
+ *
+ * @param doc {AssertionDocument}
+ * @returns {Set<string>}
+ */
+function assertionKeysOf(doc) {
+    const byId = new Map();
+    for (const method of doc.verificationMethod ?? []) {
+        if (typeof method?.id === 'string') {
+            byId.set(method.id, method);
+        }
+    }
+    const keys = new Set();
+    for (const entry of doc.assertionMethod ?? []) {
+        const method = typeof entry === 'string' ? byId.get(entry) : entry;
+        if (method && typeof method.publicKeyMultibase === 'string') {
+            keys.add(method.publicKeyMultibase);
+        }
+    }
+    return keys;
+}
+/**
+ * Builds the controller view over an already-verified did:webvh account log
+ * (the `verifyAccountLog` output -- callers never hand this a log they have
+ * not verified against the account pointer). Anchored-version lookups
+ * re-resolve the held log at that version and are memoized: controller logs
+ * are tens of entries and anchors cluster on few versions.
+ *
+ * @param options {object}
+ * @param options.did {string}   the account's did:webvh, as verified
+ * @param options.log {DIDLog}   the verified account log
+ * @returns {ResourceLogController}
+ */
+export function webvhResourceLogController({ did, log }) {
+    const versionIds = log.map(entry => entry.versionId);
+    const memo = new Map();
+    async function resolveAssertionKeys(versionId) {
+        const resolved = await resolveDIDFromLog(log, versionId === undefined ? {} : { versionId });
+        if (resolved.meta.error || !resolved.doc) {
+            throw new ResourceLogIntegrityError(`The controller document did not resolve at version ` +
+                `"${versionId ?? '<head>'}" (${resolved.meta.error ?? 'no document returned'}).`);
+        }
+        return assertionKeysOf(resolved.doc);
+    }
+    return {
+        did,
+        versionIds,
+        assertionKeysAt(versionId) {
+            const key = versionId ?? '';
+            let pending = memo.get(key);
+            if (!pending) {
+                pending = resolveAssertionKeys(versionId);
+                memo.set(key, pending);
+                pending.catch(() => memo.delete(key));
+            }
+            return pending;
+        }
+    };
+}
+//# sourceMappingURL=controller.js.map

package/dist/resourceLog/controller.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"controller.js","sourceRoot":"","sources":["../../src/resourceLog/controller.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH;;;;;;;;;;;;GAYG;AACH,OAAO,EAAE,iBAAiB,EAAe,MAAM,2BAA2B,CAAA;AAC1E,OAAO,EAAE,yBAAyB,EAAE,MAAM,aAAa,CAAA;AAkCvD;;;;;;;GAOG;AACH,SAAS,eAAe,CAAC,GAAsB;IAC7C,MAAM,IAAI,GAAG,IAAI,GAAG,EAA2C,CAAA;IAC/D,KAAK,MAAM,MAAM,IAAI,GAAG,CAAC,kBAAkB,IAAI,EAAE,EAAE,CAAC;QAClD,IAAI,OAAO,MAAM,EAAE,EAAE,KAAK,QAAQ,EAAE,CAAC;YACnC,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,EAAE,MAAM,CAAC,CAAA;QAC7B,CAAC;IACH,CAAC;IACD,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAA;IAC9B,KAAK,MAAM,KAAK,IAAI,GAAG,CAAC,eAAe,IAAI,EAAE,EAAE,CAAC;QAC9C,MAAM,MAAM,GAAG,OAAO,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAA;QAClE,IAAI,MAAM,IAAI,OAAO,MAAM,CAAC,kBAAkB,KAAK,QAAQ,EAAE,CAAC;YAC5D,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,kBAAkB,CAAC,CAAA;QACrC,CAAC;IACH,CAAC;IACD,OAAO,IAAI,CAAA;AACb,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,0BAA0B,CAAC,EACzC,GAAG,EACH,GAAG,EAIJ;IACC,MAAM,UAAU,GAAG,GAAG,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC,KAAK,CAAC,SAAS,CAAC,CAAA;IACpD,MAAM,IAAI,GAAG,IAAI,GAAG,EAAgC,CAAA;IACpD,KAAK,UAAU,oBAAoB,CACjC,SAAkB;QAElB,MAAM,QAAQ,GAAG,MAAM,iBAAiB,CACtC,GAAG,EACH,SAAS,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,CAC7C,CAAA;QACD,IAAI,QAAQ,CAAC,IAAI,CAAC,KAAK,IAAI,CAAC,QAAQ,CAAC,GAAG,EAAE,CAAC;YACzC,MAAM,IAAI,yBAAyB,CACjC,qDAAqD;gBACnD,IAAI,SAAS,IAAI,QAAQ,MACvB,QAAQ,CAAC,IAAI,CAAC,KAAK,IAAI,sBACzB,IAAI,CACP,CAAA;QACH,CAAC;QACD,OAAO,eAAe,CAAC,QAAQ,CAAC,GAAwB,CAAC,CAAA;IAC3D,CAAC;IACD,OAAO;QACL,GAAG;QACH,UAAU;QACV,eAAe,CAAC,SAAkB;YAChC,MAAM,GAAG,GAAG,SAAS,IAAI,EAAE,CAAA;YAC3B,IAAI,OAAO,GAAG,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,CAAA;YAC3B,IAAI,CAAC,OAAO,EAAE,CAAC;gBACb,OAAO,GAAG,oBAAoB,CAAC,SAAS,CAAC,CAAA;gBACzC,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,OAAO,CAAC,CAAA;gBACtB,OAAO,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAA;YACvC,CAAC;YACD,OAAO,OAAO,CAAA;QAChB,CAAC;KACF,CAAA;AACH,CAAC"}

package/dist/resourceLog/entry.d.ts

@@ -0,0 +1,68 @@
+import type { ResourceLogEntry } from '@interop/was-client/log';
+import type { ResourceLogController } from './controller.js';
+/**
+ * The writer's signing seam: its enrolled Ed25519 signing key's multibase
+ * (the fragment of its verification method in the controller document) and a
+ * raw detached-signature hook over it. The multibase names the key in the
+ * proof's `verificationMethod`; membership under `assertionMethod` at the
+ * anchored version is what authorizes the append.
+ */
+export interface ResourceLogSigner {
+    keyMultibase: string;
+    sign(input: {
+        data: Uint8Array;
+    }): Promise<Uint8Array>;
+}
+/**
+ * Builds and signs a genesis entry by the profile's two-pass SCID procedure:
+ * the preliminary entry carries the `{SCID}` placeholder as `versionId` and
+ * `parameters.scid`, its hash is the SCID, and the final entry substitutes it
+ * back in before the ordinary entry hash is computed (`versionId` input
+ * value: the SCID).
+ *
+ * @param options {object}
+ * @param options.state {ResourceLogEntry['state']}   the full initial state
+ *   (with its `type`)
+ * @param options.method {string}   the format identifier
+ *   (`WAS_RESOURCE_LOG_METHOD`)
+ * @param options.controller {ResourceLogController}   the verified controller
+ *   view -- the anchor source
+ * @param options.signer {ResourceLogSigner}
+ * @param [options.previousLog] {object}   handover successors only: the prior
+ *   log's SCID and the `versionId` of its terminal entry's predecessor
+ * @param [options.versionTime] {string}   RFC3339 UTC; defaults to now
+ * @returns {Promise<ResourceLogEntry>}
+ */
+export declare function buildResourceLogGenesis({ state, method, controller, signer, previousLog, versionTime }: {
+    state: ResourceLogEntry['state'];
+    method: string;
+    controller: ResourceLogController;
+    signer: ResourceLogSigner;
+    previousLog?: {
+        scid: string;
+        head: string;
+    };
+    versionTime?: string;
+}): Promise<ResourceLogEntry>;
+/**
+ * Builds and signs the next ordinary entry against a verified head: full
+ * state, empty `parameters`, hash chained off the head's `versionId`, proof
+ * anchored at the controller's verified head. Callers hold a verified head
+ * by construction (an entry is never built on an unverified one).
+ *
+ * @param options {object}
+ * @param options.head {ResourceLogEntry}   the verified head entry
+ * @param options.state {ResourceLogEntry['state']}   the full next state
+ * @param options.controller {ResourceLogController}
+ * @param options.signer {ResourceLogSigner}
+ * @param [options.versionTime] {string}   RFC3339 UTC; defaults to now
+ * @returns {Promise<ResourceLogEntry>}
+ */
+export declare function buildResourceLogEntry({ head, state, controller, signer, versionTime }: {
+    head: ResourceLogEntry;
+    state: ResourceLogEntry['state'];
+    controller: ResourceLogController;
+    signer: ResourceLogSigner;
+    versionTime?: string;
+}): Promise<ResourceLogEntry>;
+//# sourceMappingURL=entry.d.ts.map

package/dist/resourceLog/entry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"entry.d.ts","sourceRoot":"","sources":["../../src/resourceLog/entry.ts"],"names":[],"mappings":"AAqBA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAA;AAC/D,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,iBAAiB,CAAA;AAE5D;;;;;;GAMG;AACH,MAAM,WAAW,iBAAiB;IAChC,YAAY,EAAE,MAAM,CAAA;IACpB,IAAI,CAAC,KAAK,EAAE;QAAE,IAAI,EAAE,UAAU,CAAA;KAAE,GAAG,OAAO,CAAC,UAAU,CAAC,CAAA;CACvD;AAqFD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAsB,uBAAuB,CAAC,EAC5C,KAAK,EACL,MAAM,EACN,UAAU,EACV,MAAM,EACN,WAAW,EACX,WAAW,EACZ,EAAE;IACD,KAAK,EAAE,gBAAgB,CAAC,OAAO,CAAC,CAAA;IAChC,MAAM,EAAE,MAAM,CAAA;IACd,UAAU,EAAE,qBAAqB,CAAA;IACjC,MAAM,EAAE,iBAAiB,CAAA;IACzB,WAAW,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAA;IAC5C,WAAW,CAAC,EAAE,MAAM,CAAA;CACrB,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAmC5B;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAsB,qBAAqB,CAAC,EAC1C,IAAI,EACJ,KAAK,EACL,UAAU,EACV,MAAM,EACN,WAAW,EACZ,EAAE;IACD,IAAI,EAAE,gBAAgB,CAAA;IACtB,KAAK,EAAE,gBAAgB,CAAC,OAAO,CAAC,CAAA;IAChC,UAAU,EAAE,qBAAqB,CAAA;IACjC,MAAM,EAAE,iBAAiB,CAAA;IACzB,WAAW,CAAC,EAAE,MAAM,CAAA;CACrB,GAAG,OAAO,CAAC,gBAAgB,CAAC,CA0B5B"}