@kubun/store-credential 0.17.3 → 0.18.0

package/lib/records.js

@@ -0,0 +1,905 @@
+import { normalizeDID } from '@kokuin/token';
+import { recordClaimDigest, recordDecisionFromVerifiedCopies, recordPayloadDigest, recordPayloadMatches, recordSignerKey, verifySignedRecord } from '@kubun/records';
+import { canonicalStringify, fromB64U, fromUTF, toB64U, toUTF } from '@sozai/codec';
+/** The replicated credential record types, each projected onto one indexed table. */ export const CREDENTIAL_RECORD_TYPES = [
+    'credential.key',
+    'credential.key-branch',
+    'credential.wrapping',
+    'credential.wrapping-authority',
+    'credential.entry',
+    'credential.manifest',
+    'credential.revocation'
+];
+/** A failure about one credential record, naming it by `(type, id)`. */ export class CredentialRecordError extends Error {
+    #type;
+    #id;
+    constructor(type, id, message, options){
+        super(message, options);
+        this.name = 'CredentialRecordError';
+        this.#type = type;
+        this.#id = id;
+    }
+    get type() {
+        return this.#type;
+    }
+    get id() {
+        return this.#id;
+    }
+}
+/** Thrown when a record's payload or addressing meta does not have its type's shape. */ export class CredentialRecordPayloadError extends CredentialRecordError {
+    constructor(type, id, reason, options){
+        super(type, id, `Credential record ${type} ${id}: ${reason}`, options);
+        this.name = 'CredentialRecordPayloadError';
+    }
+}
+/** Thrown when a record's op does not verify, or does not sign its payload. */ export class CredentialRecordSignatureError extends CredentialRecordError {
+    constructor(type, id){
+        super(type, id, `Credential record ${type} ${id} is not signed by its op`);
+        this.name = 'CredentialRecordSignatureError';
+    }
+}
+/**
+ * Thrown when a stored record row cannot be read back as a record. A corrupt row is never
+ * reported as absent: an absent record admits any first write, so an older op would replace
+ * the one the row held.
+ */ export class CredentialRecordRowError extends CredentialRecordError {
+    constructor(type, id, reason){
+        super(type, id, `Stored credential record ${type} ${id} is corrupt: ${reason}`);
+        this.name = 'CredentialRecordRowError';
+    }
+}
+// Length-prefixed, so no key id can make two pairs spell one id.
+function pairID(first, second) {
+    return `${first.length}:${first}/${second}`;
+}
+/** The id of the revocation of `revokedDID` from key `keyID`. */ export function credentialRevocationRecordID(keyID, revokedDID) {
+    return pairID(keyID, normalizeDID(revokedDID));
+}
+/** The id of the manifest a grantor records for one recipient, under the record's owner. */ export function credentialManifestRecordID(recipientDID, grantorDID) {
+    return pairID(normalizeDID(recipientDID), normalizeDID(grantorDID));
+}
+function isPlainObject(value) {
+    if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+        return false;
+    }
+    const prototype = Object.getPrototypeOf(value);
+    return prototype === Object.prototype || prototype === null;
+}
+function isCount(value) {
+    return typeof value === 'number' && Number.isSafeInteger(value) && value >= 0;
+}
+function hasExactKeys(value, keys) {
+    const actual = Object.keys(value).sort();
+    const expected = [
+        ...keys
+    ].sort();
+    return actual.length === expected.length && actual.every((key, i)=>key === expected[i]);
+}
+function isStringArray(value) {
+    return Array.isArray(value) && value.every((item)=>typeof item === 'string');
+}
+class Invalid extends Error {
+}
+function fail(reason) {
+    throw new Invalid(reason);
+}
+function readBytes(value, field) {
+    if (typeof value !== 'string') fail(`${field} is not a string`);
+    let bytes;
+    try {
+        bytes = fromB64U(value);
+    } catch  {
+        fail(`${field} is not base64url`);
+    }
+    if (toB64U(bytes) !== value) fail(`${field} is not canonical base64url`);
+    return bytes;
+}
+function normalized(value, field) {
+    if (typeof value !== 'string') fail(`${field} is not a DID`);
+    try {
+        return normalizeDID(value);
+    } catch  {
+        fail(`${field} is not a DID`);
+    }
+}
+function toWire(type, payload) {
+    switch(type){
+        case 'credential.wrapping':
+            {
+                const { factors, iv, wrappedKey } = payload;
+                return {
+                    factors,
+                    iv: toB64U(iv),
+                    wrappedKey: toB64U(wrappedKey)
+                };
+            }
+        case 'credential.entry':
+            {
+                const { iv, ciphertext } = payload;
+                return {
+                    iv: toB64U(iv),
+                    ciphertext: toB64U(ciphertext)
+                };
+            }
+        default:
+            return payload;
+    }
+}
+/** The payload bytes of a credential record: canonical JSON, byte strings as base64url. */ export function encodeCredentialRecordPayload(type, payload) {
+    return fromUTF(canonicalStringify(toWire(type, payload)));
+}
+function readPayload(type, bytes) {
+    let text;
+    let parsed;
+    try {
+        text = toUTF(bytes);
+        parsed = JSON.parse(text);
+    } catch  {
+        fail('payload is not JSON');
+    }
+    if (!isPlainObject(parsed)) fail('payload is not an object');
+    if (canonicalStringify(parsed) !== text) fail('payload is not canonical JSON');
+    const p = parsed;
+    switch(type){
+        case 'credential.key':
+            if (!hasExactKeys(p, [
+                'suite',
+                'state'
+            ])) fail('payload fields');
+            if (!isCount(p.suite)) fail('suite');
+            if (p.state !== 'active' && p.state !== 'retired') fail('state');
+            return p;
+        case 'credential.key-branch':
+            if (!hasExactKeys(p, [
+                'authorDID',
+                'hlc',
+                'opJWT',
+                'opHash',
+                'suite'
+            ])) fail('payload fields');
+            for (const field of [
+                'authorDID',
+                'hlc',
+                'opJWT',
+                'opHash'
+            ]){
+                if (typeof p[field] !== 'string') fail(field);
+            }
+            if (!isCount(p.suite)) fail('suite');
+            return p;
+        case 'credential.wrapping':
+            {
+                if (!hasExactKeys(p, [
+                    'factors',
+                    'iv',
+                    'wrappedKey'
+                ])) fail('payload fields');
+                const factors = p.factors;
+                if (!Array.isArray(factors) || !factors.every((factor)=>isPlainObject(factor) && hasExactKeys(factor, [
+                        'kind',
+                        'params'
+                    ]) && typeof factor.kind === 'string' && isPlainObject(factor.params))) {
+                    fail('factors');
+                }
+                return {
+                    factors,
+                    iv: readBytes(p.iv, 'iv'),
+                    wrappedKey: readBytes(p.wrappedKey, 'wrappedKey')
+                };
+            }
+        case 'credential.wrapping-authority':
+            if (!hasExactKeys(p, [
+                'envelope'
+            ]) || typeof p.envelope !== 'string') fail('envelope');
+            return p;
+        case 'credential.entry':
+            if (!hasExactKeys(p, [
+                'iv',
+                'ciphertext'
+            ])) fail('payload fields');
+            return {
+                iv: readBytes(p.iv, 'iv'),
+                ciphertext: readBytes(p.ciphertext, 'ciphertext')
+            };
+        case 'credential.manifest':
+            {
+                if (!hasExactKeys(p, [
+                    'keys',
+                    'token',
+                    'delegationTokens'
+                ])) fail('payload fields');
+                const keys = p.keys;
+                if (!Array.isArray(keys) || !keys.every((key)=>isPlainObject(key) && hasExactKeys(key, [
+                        'keyID',
+                        'version'
+                    ]) && typeof key.keyID === 'string' && isCount(key.version))) {
+                    fail('keys');
+                }
+                if (typeof p.token !== 'string') fail('token');
+                if (!isStringArray(p.delegationTokens)) fail('delegationTokens');
+                return p;
+            }
+        case 'credential.revocation':
+            if (!hasExactKeys(p, [])) fail('payload fields');
+            return p;
+    }
+}
+function readBranchID(value) {
+    if (typeof value !== 'string' || value === '') fail('meta.branchID');
+    return value;
+}
+function readMeta(type, id, payloadBytes, m) {
+    switch(type){
+        case 'credential.key':
+            if (m.keyID !== id) fail('meta.keyID is not the record id');
+            if (!isCount(m.version)) fail('meta.version');
+            return {
+                keyID: m.keyID,
+                version: m.version
+            };
+        case 'credential.key-branch':
+            if (id !== recordPayloadDigest(payloadBytes)) fail('record id is not the payload digest');
+            if (typeof m.keyID !== 'string') fail('meta.keyID');
+            if (!isCount(m.keyVersion)) fail('meta.keyVersion');
+            if (typeof m.branchID !== 'string') fail('meta.branchID');
+            return {
+                keyID: m.keyID,
+                keyVersion: m.keyVersion,
+                branchID: m.branchID
+            };
+        case 'credential.wrapping':
+            if (typeof m.keyID !== 'string') fail('meta.keyID');
+            if (!isCount(m.keyVersion)) fail('meta.keyVersion');
+            return {
+                keyID: m.keyID,
+                keyVersion: m.keyVersion,
+                branchID: readBranchID(m.branchID),
+                recipient: m.recipient == null ? null : normalized(m.recipient, 'meta.recipient')
+            };
+        case 'credential.wrapping-authority':
+            if (m.wrappingID !== id) fail('meta.wrappingID is not the record id');
+            if (!isCount(m.refreshSeq)) fail('meta.refreshSeq');
+            return {
+                wrappingID: m.wrappingID,
+                refreshSeq: m.refreshSeq
+            };
+        case 'credential.entry':
+            if (typeof m.keyID !== 'string') fail('meta.keyID');
+            if (!isCount(m.keyVersion)) fail('meta.keyVersion');
+            return {
+                keyID: m.keyID,
+                keyVersion: m.keyVersion,
+                branchID: readBranchID(m.branchID)
+            };
+        case 'credential.manifest':
+            {
+                const recipient = normalized(m.recipient, 'meta.recipient');
+                const grantor = normalized(m.grantor, 'meta.grantor');
+                if (id !== pairID(recipient, grantor)) fail('record id does not name its recipient and grantor');
+                if (!isCount(m.epoch)) fail('meta.epoch');
+                if (!isCount(m.sequence)) fail('meta.sequence');
+                return {
+                    recipient,
+                    grantor,
+                    epoch: m.epoch,
+                    sequence: m.sequence
+                };
+            }
+        case 'credential.revocation':
+            {
+                if (typeof m.keyID !== 'string') fail('meta.keyID');
+                const revokedDID = normalized(m.revokedDID, 'meta.revokedDID');
+                if (id !== pairID(m.keyID, revokedDID)) fail('record id does not name its key and recipient');
+                return {
+                    keyID: m.keyID,
+                    revokedDID
+                };
+            }
+    }
+}
+function isCredentialRecordType(type) {
+    return CREDENTIAL_RECORD_TYPES.includes(type);
+}
+/**
+ * Decode a live credential record's payload and the meta fields that address its indexed
+ * row. DIDs the store keys on are returned normalized. A type's authorizer can call this to
+ * refuse a record the store would not accept.
+ *
+ * @throws CredentialRecordPayloadError when the type is not a credential type, the record is
+ * a tombstone, or its payload or meta does not have the type's shape.
+ */ export function decodeCredentialRecord(record, meta) {
+    const { type, id, owner, hlc, payload } = record;
+    try {
+        if (!isCredentialRecordType(type)) fail('not a credential record type');
+        if (payload === null) fail('a tombstone has no payload');
+        if (!isPlainObject(meta)) fail('meta is not an object');
+        return {
+            type,
+            id,
+            owner,
+            hlc,
+            meta: readMeta(type, id, payload, meta),
+            payload: readPayload(type, payload)
+        };
+    } catch (error) {
+        if (error instanceof Invalid) {
+            // biome-ignore lint/style/useErrorCause: the cause rides the fourth argument
+            throw new CredentialRecordPayloadError(type, id, error.message, {
+                cause: error
+            });
+        }
+        throw error;
+    }
+}
+// A tombstone removes only its owner's indexed row.
+async function removeByID(tx, type, owner, id) {
+    switch(type){
+        case 'credential.key':
+            await tx.deleteFrom('kubun_credential_keys').where('owner_did', '=', owner).where('key_id', '=', id).execute();
+            return;
+        case 'credential.wrapping':
+            await tx.deleteFrom('kubun_credential_wrappings').where('owner_did', '=', owner).where('wrapping_id', '=', id).execute();
+            return;
+        case 'credential.wrapping-authority':
+            await tx.deleteFrom('kubun_credential_wrapping_authority').where('owner_did', '=', owner).where('wrapping_id', '=', id).execute();
+            return;
+        case 'credential.entry':
+            await tx.deleteFrom('kubun_credential_entries').where('owner_did', '=', owner).where('entry_id', '=', id).execute();
+            return;
+        default:
+            return;
+    }
+}
+function projectionOf(record, adapter) {
+    const byID = {
+        address: JSON.stringify([
+            record.owner,
+            record.id
+        ]),
+        remove: (tx)=>removeByID(tx, record.type, record.owner, record.id)
+    };
+    switch(record.type){
+        case 'credential.key':
+            {
+                const values = {
+                    key_id: record.id,
+                    owner_did: record.owner,
+                    suite: record.payload.suite,
+                    version: record.meta.version,
+                    state: record.payload.state
+                };
+                return {
+                    ...byID,
+                    write: async (tx)=>{
+                        await tx.insertInto('kubun_credential_keys').values(values).onConflict((oc)=>oc.columns([
+                                'owner_did',
+                                'key_id'
+                            ]).doUpdateSet({
+                                suite: values.suite,
+                                version: values.version,
+                                state: values.state
+                            })).execute();
+                    }
+                };
+            }
+        case 'credential.key-branch':
+            {
+                const values = {
+                    owner_did: record.owner,
+                    key_id: record.meta.keyID,
+                    key_version: record.meta.keyVersion,
+                    op_hash: record.payload.opHash,
+                    author_did: record.payload.authorDID,
+                    hlc: record.payload.hlc,
+                    op_jwt: record.payload.opJWT,
+                    branch_id: record.meta.branchID
+                };
+                return {
+                    address: JSON.stringify([
+                        values.owner_did,
+                        values.key_id,
+                        values.key_version,
+                        values.op_hash
+                    ]),
+                    write: async (tx)=>{
+                        await tx.insertInto('kubun_credential_key_branches').values(values).onConflict((oc)=>oc.columns([
+                                'owner_did',
+                                'key_id',
+                                'key_version',
+                                'op_hash'
+                            ]).doUpdateSet({
+                                author_did: values.author_did,
+                                hlc: values.hlc,
+                                op_jwt: values.op_jwt,
+                                branch_id: values.branch_id
+                            })).execute();
+                    },
+                    remove: async (tx)=>{
+                        await tx.deleteFrom('kubun_credential_key_branches').where('owner_did', '=', values.owner_did).where('key_id', '=', values.key_id).where('key_version', '=', values.key_version).where('op_hash', '=', values.op_hash).execute();
+                    }
+                };
+            }
+        case 'credential.wrapping':
+            {
+                const values = {
+                    owner_did: record.owner,
+                    wrapping_id: record.id,
+                    key_id: record.meta.keyID,
+                    key_version: record.meta.keyVersion,
+                    factors: adapter.encodeJSON(record.payload.factors),
+                    iv: adapter.encodeBinary(record.payload.iv),
+                    wrapped_key: adapter.encodeBinary(record.payload.wrappedKey),
+                    recipient_did: record.meta.recipient ?? null,
+                    branch_id: record.meta.branchID
+                };
+                return {
+                    ...byID,
+                    write: async (tx)=>{
+                        await tx.insertInto('kubun_credential_wrappings').values(values).onConflict((oc)=>oc.columns([
+                                'owner_did',
+                                'wrapping_id'
+                            ]).doUpdateSet({
+                                key_id: values.key_id,
+                                key_version: values.key_version,
+                                factors: values.factors,
+                                iv: values.iv,
+                                wrapped_key: values.wrapped_key,
+                                recipient_did: values.recipient_did,
+                                branch_id: values.branch_id
+                            })).execute();
+                    }
+                };
+            }
+        case 'credential.wrapping-authority':
+            {
+                const values = {
+                    owner_did: record.owner,
+                    wrapping_id: record.id,
+                    authority_token: record.payload.envelope,
+                    refresh_seq: record.meta.refreshSeq
+                };
+                return {
+                    ...byID,
+                    write: async (tx)=>{
+                        await tx.insertInto('kubun_credential_wrapping_authority').values(values).onConflict((oc)=>oc.columns([
+                                'owner_did',
+                                'wrapping_id'
+                            ]).doUpdateSet({
+                                authority_token: values.authority_token,
+                                refresh_seq: values.refresh_seq
+                            })).execute();
+                    }
+                };
+            }
+        case 'credential.entry':
+            {
+                const values = {
+                    owner_did: record.owner,
+                    entry_id: record.id,
+                    key_id: record.meta.keyID,
+                    key_version: record.meta.keyVersion,
+                    iv: adapter.encodeBinary(record.payload.iv),
+                    ciphertext: adapter.encodeBinary(record.payload.ciphertext),
+                    hlc: record.hlc,
+                    branch_id: record.meta.branchID
+                };
+                return {
+                    ...byID,
+                    write: async (tx)=>{
+                        await tx.insertInto('kubun_credential_entries').values(values).onConflict((oc)=>oc.columns([
+                                'owner_did',
+                                'entry_id'
+                            ]).doUpdateSet({
+                                key_id: values.key_id,
+                                key_version: values.key_version,
+                                iv: values.iv,
+                                ciphertext: values.ciphertext,
+                                hlc: values.hlc,
+                                branch_id: values.branch_id
+                            })).execute();
+                    }
+                };
+            }
+        case 'credential.manifest':
+            {
+                const values = {
+                    owner_did: record.owner,
+                    recipient_did: record.meta.recipient,
+                    grantor_did: record.meta.grantor,
+                    epoch: record.meta.epoch,
+                    sequence: record.meta.sequence,
+                    keys_json: adapter.encodeJSON(record.payload.keys),
+                    manifest_token: record.payload.token,
+                    delegation_tokens: adapter.encodeJSON(record.payload.delegationTokens)
+                };
+                return {
+                    address: JSON.stringify([
+                        values.owner_did,
+                        values.recipient_did,
+                        values.grantor_did
+                    ]),
+                    write: async (tx)=>{
+                        await tx.insertInto('kubun_credential_manifests').values(values).onConflict((oc)=>oc.columns([
+                                'owner_did',
+                                'recipient_did',
+                                'grantor_did'
+                            ]).doUpdateSet({
+                                epoch: values.epoch,
+                                sequence: values.sequence,
+                                keys_json: values.keys_json,
+                                manifest_token: values.manifest_token,
+                                delegation_tokens: values.delegation_tokens
+                            })).execute();
+                    },
+                    remove: async (tx)=>{
+                        await tx.deleteFrom('kubun_credential_manifests').where('owner_did', '=', values.owner_did).where('recipient_did', '=', values.recipient_did).where('grantor_did', '=', values.grantor_did).execute();
+                    }
+                };
+            }
+        case 'credential.revocation':
+            {
+                const values = {
+                    key_id: record.meta.keyID,
+                    recipient_did: record.meta.revokedDID,
+                    owner_did: record.owner
+                };
+                return {
+                    address: JSON.stringify([
+                        values.owner_did,
+                        values.key_id,
+                        values.recipient_did
+                    ]),
+                    write: async (tx)=>{
+                        await tx.insertInto('kubun_credential_revocations').values(values).onConflict((oc)=>oc.columns([
+                                'owner_did',
+                                'key_id',
+                                'recipient_did'
+                            ]).doNothing()).execute();
+                    },
+                    remove: async (tx)=>{
+                        await tx.deleteFrom('kubun_credential_revocations').where('owner_did', '=', values.owner_did).where('key_id', '=', values.key_id).where('recipient_did', '=', values.recipient_did).execute();
+                    }
+                };
+            }
+    }
+}
+function rowFailure(row, reason) {
+    throw new CredentialRecordRowError(String(row.type), String(row.id), reason);
+}
+function rowMeta(row) {
+    // SQLite hands JSON back as text when the parse plugin could not read it.
+    const meta = typeof row.meta === 'string' ? safeParse(row.meta) : row.meta;
+    if (!isPlainObject(meta)) rowFailure(row, 'meta is not an object');
+    return meta;
+}
+function safeParse(text) {
+    try {
+        return JSON.parse(text);
+    } catch  {
+        return undefined;
+    }
+}
+/**
+ * A stored row as the record it holds. The signature is not checked here — apply verifies
+ * every stored op it reads — but everything the row repeats must agree with itself.
+ *
+ * @throws CredentialRecordRowError when it does not.
+ */ export function credentialRecordFromRow(row) {
+    for (const field of [
+        'type',
+        'id',
+        'owner',
+        'hlc',
+        'op_jwt',
+        'op_hash'
+    ]){
+        if (typeof row[field] !== 'string' || row[field] === '') rowFailure(row, `${field} is empty`);
+    }
+    if (row.deleted !== 0 && row.deleted !== 1) rowFailure(row, 'deleted is not 0 or 1');
+    const payload = row.payload == null ? null : Uint8Array.from(row.payload);
+    if (row.deleted === 1 !== (payload === null)) {
+        rowFailure(row, 'a tombstone must have no payload, and a live record one');
+    }
+    if (recordPayloadDigest(payload) !== row.payload_digest) {
+        rowFailure(row, 'payload does not match its digest');
+    }
+    rowMeta(row);
+    return {
+        type: row.type,
+        id: row.id,
+        owner: row.owner,
+        hlc: row.hlc,
+        payload,
+        opJWT: row.op_jwt,
+        opHash: row.op_hash
+    };
+}
+/** Keep every authenticated entry operation for branch comparison, including a losing op. */ export async function retainCredentialEntryCandidate(tx, record, claim, adapter) {
+    if (record.type !== 'credential.entry') return;
+    const { keyID, keyVersion, branchID } = claim.meta;
+    if (typeof keyID !== 'string' || typeof keyVersion !== 'number') return;
+    await tx.insertInto('kubun_credential_entry_candidates').values({
+        key_id: keyID,
+        owner_did: claim.owner,
+        key_version: keyVersion,
+        branch_id: typeof branchID === 'string' ? branchID : '',
+        entry_id: record.id,
+        owner: record.owner,
+        hlc: record.hlc,
+        op_jwt: record.opJWT,
+        op_hash: record.opHash,
+        payload: record.payload === null ? null : adapter.encodeBinary(record.payload)
+    }).onConflict((oc)=>oc.columns([
+            'owner_did',
+            'entry_id',
+            'op_hash'
+        ]).doNothing()).execute();
+}
+/**
+ * Store a copy of the selected decision of its `(type, owner, id)`, and
+ * bring its indexed row along in the same transaction: a live record writes its row, a
+ * tombstone removes the row the previous op projected, and a record whose index address
+ * moved removes its old row. Merge decisions are the caller's; this only checks that the
+ * record is signed and has its type's shape, before anything is written.
+ *
+ * @throws CredentialRecordSignatureError when the op does not verify or sign the payload.
+ * @throws CredentialRecordPayloadError when a live record does not have its type's shape.
+ * @throws CredentialRecordRowError when the row it replaces is corrupt.
+ */ export async function putCredentialRecord(params) {
+    const { record, adapter, write, methods, lockKey, verifiedCopies } = params;
+    if (!isCredentialRecordType(record.type)) {
+        throw new CredentialRecordPayloadError(record.type, record.id, 'not a credential record type');
+    }
+    const type = record.type;
+    const op = await verifySignedRecord(record, methods);
+    if (op === null || !recordPayloadMatches(record, op.claim)) {
+        throw new CredentialRecordSignatureError(record.type, record.id);
+    }
+    const claim = op.claim;
+    const cacheKey = JSON.stringify([
+        record.type,
+        record.owner,
+        record.id
+    ]);
+    const known = verifiedCopies.get(cacheKey);
+    let nextKnown = null;
+    const next = claim.deleted ? null : projectionOf(decodeCredentialRecord(record, claim.meta), adapter);
+    await write(async (tx)=>{
+        const keyID = claim.meta.keyID;
+        if (typeof keyID === 'string') await lockKey(tx, keyID);
+        const previousRows = await tx.selectFrom('kubun_credential_records').selectAll().where('type', '=', type).where('owner', '=', claim.owner).where('id', '=', record.id).orderBy('op_hash', 'asc').execute();
+        let previousRow;
+        let stored = null;
+        let previousOp = null;
+        let firstRowError = null;
+        const validRows = new Map();
+        for (const row of previousRows){
+            let candidate;
+            try {
+                candidate = credentialRecordFromRow(row);
+            } catch (error) {
+                if (!(error instanceof CredentialRecordRowError)) throw error;
+                firstRowError ??= error;
+                continue;
+            }
+            const knownCopy = known?.get(candidate.opHash);
+            const trusted = knownCopy !== undefined && knownCopy.copy.type === candidate.type && knownCopy.copy.id === candidate.id && knownCopy.copy.owner === candidate.owner && knownCopy.copy.opJWT === candidate.opJWT && knownCopy.copy.hlc === candidate.hlc && recordPayloadDigest(knownCopy.copy.payload) === recordPayloadDigest(candidate.payload);
+            const verified = trusted ? knownCopy.op : await verifySignedRecord(candidate, methods);
+            if (verified === null || !recordPayloadMatches(candidate, verified.claim)) continue;
+            validRows.set(row.op_hash, {
+                copy: candidate,
+                op: verified
+            });
+            if (previousRow === undefined) {
+                previousRow = row;
+                stored = candidate;
+                previousOp = verified;
+            }
+        }
+        if (previousRow === undefined && firstRowError !== null) throw firstRowError;
+        let previous = null;
+        // Read back before the liveness check, so a corrupt row fails closed rather than
+        // being taken for a tombstone and written over.
+        const sameDecision = previousOp !== null && recordClaimDigest(previousOp.claim) === recordClaimDigest(claim) && (typeof previousOp.claim.meta.version === 'string' ? previousOp.claim.meta.version : previousOp.claim.hlc) === (typeof claim.meta.version === 'string' ? claim.meta.version : claim.hlc);
+        if (previousRow != null && stored !== null && stored.payload !== null) {
+            try {
+                previous = projectionOf(decodeCredentialRecord(stored, rowMeta(previousRow)), adapter);
+            } catch (error) {
+                if (error instanceof CredentialRecordPayloadError) {
+                    rowFailure(previousRow, error.message);
+                }
+                throw error;
+            }
+        }
+        const values = {
+            type,
+            id: record.id,
+            owner: record.owner,
+            hlc: record.hlc,
+            op_jwt: record.opJWT,
+            op_hash: record.opHash,
+            payload_digest: claim.payloadDigest,
+            payload: record.payload == null ? null : adapter.encodeBinary(record.payload),
+            deleted: claim.deleted ? 1 : 0,
+            meta: adapter.encodeJSON(claim.meta)
+        };
+        if (!sameDecision) {
+            await tx.deleteFrom('kubun_credential_records').where('type', '=', type).where('owner', '=', claim.owner).where('id', '=', record.id).execute();
+        } else {
+            for (const row of previousRows){
+                if (!validRows.has(row.op_hash)) {
+                    credentialRecordFromRow(row);
+                    await tx.deleteFrom('kubun_credential_records').where('type', '=', type).where('owner', '=', claim.owner).where('id', '=', record.id).where('op_hash', '=', row.op_hash).execute();
+                }
+            }
+        }
+        await tx.insertInto('kubun_credential_records').values(values).onConflict((oc)=>oc.columns([
+                'type',
+                'owner',
+                'id',
+                'op_hash'
+            ]).doNothing()).execute();
+        if (sameDecision) {
+            const incomingSigner = recordSignerKey(op.issuer, record.opJWT);
+            const sameSigner = [
+                ...validRows
+            ].filter(([, value])=>recordSignerKey(value.op.issuer, value.copy.opJWT) === incomingSigner);
+            const keepHash = [
+                record.opHash,
+                ...sameSigner.map(([hash])=>hash)
+            ].sort()[0];
+            for (const [hash] of sameSigner){
+                if (hash !== keepHash) {
+                    await tx.deleteFrom('kubun_credential_records').where('type', '=', type).where('owner', '=', claim.owner).where('id', '=', record.id).where('op_hash', '=', hash).execute();
+                }
+            }
+            if (record.opHash !== keepHash) {
+                await tx.deleteFrom('kubun_credential_records').where('type', '=', type).where('owner', '=', claim.owner).where('id', '=', record.id).where('op_hash', '=', record.opHash).execute();
+            }
+            nextKnown = new Map(validRows);
+            for (const [hash] of sameSigner){
+                if (hash !== keepHash) nextKnown.delete(hash);
+            }
+            if (record.opHash === keepHash) nextKnown.set(record.opHash, {
+                copy: record,
+                op
+            });
+            await retainCredentialEntryCandidate(tx, record, claim, adapter);
+            return;
+        }
+        if (previous !== null && previous.address !== next?.address) {
+            await previous.remove(tx);
+        }
+        if (next !== null) {
+            await next.write(tx);
+        } else if (previous !== null) {
+            await removeByID(tx, type, claim.owner, record.id);
+        }
+        await retainCredentialEntryCandidate(tx, record, claim, adapter);
+        nextKnown = new Map([
+            [
+                record.opHash,
+                {
+                    copy: record,
+                    op
+                }
+            ]
+        ]);
+    });
+    if (nextKnown !== null) verifiedCopies.set(cacheKey, nextKnown);
+}
+async function decisionFromRows(rows, methods) {
+    const verified = [];
+    let firstError = null;
+    for (const row of rows){
+        let copy;
+        try {
+            copy = credentialRecordFromRow(row);
+        } catch (error) {
+            if (!(error instanceof CredentialRecordRowError)) throw error;
+            firstError ??= error;
+            continue;
+        }
+        const op = await verifySignedRecord(copy, methods);
+        if (op === null || !recordPayloadMatches(copy, op.claim)) continue;
+        verified.push({
+            copy,
+            op
+        });
+    }
+    const first = verified[0];
+    const decision = first === undefined ? null : recordDecisionFromVerifiedCopies({
+        type: first.copy.type,
+        owner: first.op.claim.owner,
+        id: first.copy.id
+    }, verified, 'hlc');
+    if (decision === null && firstError !== null) throw firstError;
+    return decision;
+}
+/**
+ * The records primitive's view of the credential store.
+ *
+ * `get` throws {@link CredentialRecordRowError} on a corrupt row rather than answering
+ * absent, so apply fails closed on it. `list` skips such a row, reporting it through
+ * `onCorruptRow`, so one bad row does not hide every other record of its type. Rows the
+ * legacy verbs wrote into the indexed tables are not records and never appear.
+ */ export function credentialRecordAdapter(store, options = {}) {
+    const adapter = {
+        isTransaction: store.isTransaction,
+        async transaction (fn) {
+            return await store.transaction(async (tx)=>await fn(credentialRecordAdapter(tx, options)));
+        },
+        async get (key) {
+            if (!isCredentialRecordType(key.type)) return null;
+            return await decisionFromRows(await store.getRecordRows(key), options.methods);
+        },
+        async getMany (keys) {
+            const rowsByKey = await store.getRecordRowsForKeys(keys.filter((key)=>isCredentialRecordType(key.type)));
+            const decisions = new Map();
+            for (const [text, rows] of rowsByKey){
+                const decision = await decisionFromRows(rows, options.methods);
+                if (decision !== null) decisions.set(text, decision);
+            }
+            return decisions;
+        },
+        async list (types) {
+            const decisions = [];
+            const groups = new Map();
+            for (const row of (await store.listRecordRows(types))){
+                if (!isCredentialRecordType(row.type)) continue;
+                const key = `${row.type}\u0000${row.owner}\u0000${row.id}`;
+                const rows = groups.get(key) ?? [];
+                rows.push(row);
+                groups.set(key, rows);
+            }
+            for (const rows of groups.values()){
+                try {
+                    const decision = await decisionFromRows(rows, options.methods);
+                    if (decision !== null) decisions.push(decision);
+                } catch (error) {
+                    if (!(error instanceof CredentialRecordRowError)) throw error;
+                    const row = rows[0];
+                    options.onCorruptRow?.({
+                        type: row.type,
+                        id: row.id,
+                        error
+                    });
+                }
+            }
+            return decisions;
+        },
+        async putCopy (record) {
+            await store.putRecord(record, options.methods);
+        },
+        async pruneCopy (key, signerDID) {
+            if (!isCredentialRecordType(key.type)) return;
+            await store.transaction(async (tx)=>{
+                const decision = await decisionFromRows(await tx.getRecordRows(key), options.methods);
+                if (decision === null || decision.copies.length < 2) return;
+                for (const copy of decision.copies){
+                    const op = await verifySignedRecord(copy, options.methods);
+                    if (op !== null && normalizeDID(op.issuer) === normalizeDID(signerDID)) {
+                        await tx.deleteRecordCopy(key, copy.opHash);
+                    }
+                }
+            });
+        },
+        async retainCredentialEntryCandidate (record, methods) {
+            await store.retainEntryCandidate(record, methods);
+        },
+        async lock (keys) {
+            await store.lockKeyRows(keys.map((key)=>key.key));
+        }
+    };
+    adapterStores.set(adapter, store);
+    return adapter;
+}
+const adapterStores = new WeakMap();
+/**
+ * The credential store behind an adapter {@link credentialRecordAdapter} made, bound to the
+ * same transaction, or `null` for any other adapter. A record type's hooks receive only the
+ * adapter; this lets them reach the indexed tables inside the transaction they run in,
+ * rather than through a store bound outside it.
+ */ export function credentialStoreOf(adapter) {
+    return adapterStores.get(adapter) ?? null;
+}