@kubun/store-credential 0.13.0

package/LICENSE.md

@@ -0,0 +1,57 @@
+# The Prosperity Public License 3.0.0
+
+Contributor: Paul Le Cam
+
+Source Code: https://github.com/PaulLeCam/kubun
+
+## Purpose
+
+This license allows you to use and share this software for noncommercial purposes for free and to try this software for commercial purposes for thirty days.
+
+## Agreement
+
+In order to receive this license, you have to agree to its rules.  Those rules are both obligations under that agreement and conditions to your license.  Don't do anything with this software that triggers a rule you can't or won't follow.
+
+## Notices
+
+Make sure everyone who gets a copy of any part of this software from you, with or without changes, also gets the text of this license and the contributor and source code lines above.
+
+## Commercial Trial
+
+Limit your use of this software for commercial purposes to a thirty-day trial period.  If you use this software for work, your company gets one trial period for all personnel, not one trial per person.
+
+## Contributions Back
+
+Developing feedback, changes, or additions that you contribute back to the contributor on the terms of a standardized public software license such as [the Blue Oak Model License 1.0.0](https://blueoakcouncil.org/license/1.0.0), [the Apache License 2.0](https://www.apache.org/licenses/LICENSE-2.0.html), [the MIT license](https://spdx.org/licenses/MIT.html), or [the two-clause BSD license](https://spdx.org/licenses/BSD-2-Clause.html) doesn't count as use for a commercial purpose.
+
+## Personal Uses
+
+Personal use for research, experiment, and testing for the benefit of public knowledge, personal study, private entertainment, hobby projects, amateur pursuits, or religious observance, without any anticipated commercial application, doesn't count as use for a commercial purpose.
+
+## Noncommercial Organizations
+
+Use by any charitable organization, educational institution, public research organization, public safety or health organization, environmental protection organization, or government institution doesn't count as use for a commercial purpose regardless of the source of funding or obligations resulting from the funding.
+
+## Defense
+
+Don't make any legal claim against anyone accusing this software, with or without changes, alone or with other technology, of infringing any patent.
+
+## Copyright
+
+The contributor licenses you to do everything with this software that would otherwise infringe their copyright in it.
+
+## Patent
+
+The contributor licenses you to do everything with this software that would otherwise infringe any patents they can license or become able to license.
+
+## Reliability
+
+The contributor can't revoke this license.
+
+## Excuse
+
+You're excused for unknowingly breaking [Notices](#notices) if you take all practical steps to comply within thirty days of learning you broke the rule.
+
+## No Liability
+
+***As far as the law allows, this software comes as is, without any warranty or condition, and the contributor won't be liable to anyone for any damages related to this software or this license, under any kind of legal claim.***

package/lib/api.d.ts

@@ -0,0 +1,159 @@
+import type { Adapter } from '@kubun/db-adapter';
+import type { Kysely } from 'kysely';
+import type { CredentialEntry, CredentialEntryWithProvenance, CredentialFactorDescriptor, CredentialKey, CredentialKeyBranch, CredentialKeyState, CredentialOp, CredentialOpSubjectKind, CredentialTables, CredentialWrapping, CredentialWrappingWithBranch } from './tables.js';
+/**
+ * The signed op that produced a row's current state, as the store holds it.
+ *
+ * `opJWT` is opaque here — this package neither signs nor verifies, the same way
+ * it neither encrypts nor decrypts. `@kubun/credential` mints these and is the
+ * only thing that can read one.
+ */
+export type CredentialOpInput = {
+    keyID: string;
+    authorDID: string;
+    hlc: string;
+    opJWT: string;
+    opHash: string;
+    /**
+     * The content-key branch this op joins — `${hlc}:${opHash}` of the branch's
+     * introducing key-op. Empty when the op is minted outside a rotation/create
+     * and so does not resolve the branch it belongs to.
+     */
+    branchID: string;
+};
+/** A tombstone for one subject of a multi-row delete, which names its own. */
+export type CredentialTombstoneInput = CredentialOpInput & {
+    subjectID: string;
+};
+export type PutCredentialKeyParams = {
+    keyID: string;
+    ownerDID: string;
+    suite: number;
+    version: number;
+    state: CredentialKeyState;
+};
+export type PutCredentialWrappingParams = {
+    wrappingID: string;
+    keyID: string;
+    keyVersion: number;
+    factors: Array<CredentialFactorDescriptor>;
+    iv: Uint8Array;
+    wrappedKey: Uint8Array;
+    recipientDID?: string | null;
+};
+export type PutCredentialEntryParams = {
+    entryID: string;
+    keyID: string;
+    keyVersion: number;
+    iv: Uint8Array;
+    ciphertext: Uint8Array;
+    hlc: string;
+};
+export type HeldCredentialSubject = {
+    subjectKind: CredentialOpSubjectKind;
+    subjectID: string;
+    opHash: string;
+};
+/**
+ * Persistence for credential keys, wrappings and entries.
+ *
+ * Storage only: nothing here wraps, unwraps, encrypts or decrypts, and nothing
+ * here interprets a ciphertext. `ciphertext` and `wrapped_key` are opaque byte
+ * strings that come back exactly as they went in — not parsed as JSON, not
+ * decoded as UTF-8, not validated in any way. A caller owning the crypto is what
+ * lets the suite change without a migration.
+ *
+ * A deletion is NOT the absence of a row. It is a tombstone in
+ * `kubun_credential_ops`, and the row is gone from its own table — so asking
+ * whether a wrapping exists means reading two tables, not one. Absence alone
+ * cannot travel over a lane that only adds: a peer holding the deleted row would
+ * ship it back and this device would store it again. So a `put` carrying an op no
+ * newer than the tombstone writes NOTHING, silently — that is the resend.
+ *
+ * The op is REQUIRED, and `null` is how a writer says it has none rather than
+ * how it says nothing. A row written with `null` is stored but speaks for
+ * itself, invisible to the sync lane; making the parameter mandatory is what
+ * stops a write path added later from being silently unsigned. Only the GraphQL
+ * query context passes it today: it holds a viewer's DID and no signing key.
+ */
+export type CredentialStoreAPI = {
+    putKey(params: PutCredentialKeyParams, op: CredentialOpInput | null): Promise<void>;
+    getKey(keyID: string): Promise<CredentialKey | undefined>;
+    listKeys(ownerDID: string): Promise<Array<CredentialKey>>;
+    setKeyState(keyID: string, state: CredentialKeyState, op: CredentialOpInput | null): Promise<void>;
+    /** Bump a key to a new version. Wrappings and entries at earlier versions stay. */
+    setKeyVersion(keyID: string, version: number, op: CredentialOpInput | null): Promise<void>;
+    deleteKey(keyID: string, tombstone: CredentialOpInput | null): Promise<void>;
+    recordKeyBranch(params: {
+        keyID: string;
+        keyVersion: number;
+        authorDID: string;
+        hlc: string;
+        opJWT: string;
+        opHash: string;
+        branchID: string;
+    }): Promise<void>;
+    listKeyBranches(keyID: string, keyVersion: number): Promise<Array<CredentialKeyBranch>>;
+    putWrapping(params: PutCredentialWrappingParams, op: CredentialOpInput | null): Promise<void>;
+    getWrapping(wrappingID: string): Promise<CredentialWrapping | undefined>;
+    /** Every wrapping for a key, or only those at one version. */
+    listWrappings(keyID: string, keyVersion?: number): Promise<Array<CredentialWrapping>>;
+    /**
+     * As {@link listWrappings}, each row carrying its op's `branch_id`. The
+     * fork-aware read path needs the label to resolve which content-key branch a
+     * device opens; every other caller reads none, so the join stays off the
+     * common path.
+     */
+    listWrappingsWithBranch(keyID: string, keyVersion?: number): Promise<Array<CredentialWrappingWithBranch>>;
+    deleteWrapping(wrappingID: string, tombstone: CredentialOpInput | null): Promise<void>;
+    /**
+     * Drop every wrapping for a key below `keyVersion` — what a rotation leaves
+     * behind. The tombstones name their own subjects, because the caller decides
+     * which rows it is accounting for and the delete predicate spans many.
+     */
+    deleteWrappingsBelowVersion(keyID: string, keyVersion: number, tombstones: Array<CredentialTombstoneInput> | null): Promise<void>;
+    putEntry(params: PutCredentialEntryParams, op: CredentialOpInput | null): Promise<void>;
+    /**
+     * Explicitly change an entry's key association. Callers must authorize both
+     * source and target keys before invoking this capability.
+     */
+    moveEntry(params: PutCredentialEntryParams, op: CredentialOpInput | null): Promise<void>;
+    getEntry(entryID: string): Promise<CredentialEntry | undefined>;
+    getEntryWithProvenance(entryID: string): Promise<CredentialEntryWithProvenance | undefined>;
+    listEntries(keyID: string): Promise<Array<CredentialEntry>>;
+    /**
+     * Greatest stored entry HLC, or `null` when there are none. Credential writes
+     * advance the device clock but leave no row in the graph mutation log, so this
+     * is the only trace they leave for a restart floor to read.
+     */
+    getMaxEntryHLC(): Promise<string | null>;
+    deleteEntry(entryID: string, tombstone: CredentialOpInput | null): Promise<void>;
+    /** The op a subject's current state came from, tombstone included. */
+    getOp(subjectKind: CredentialOpSubjectKind, subjectID: string): Promise<CredentialOp | undefined>;
+    /**
+     * Ops in stamp order — every one, or one key's. This is the merkle lane's leaf
+     * scan, which is why the ops of all three subject kinds share a table.
+     */
+    listOps(keyID?: string): Promise<Array<CredentialOp>>;
+    /**
+     * The leaf scan scoped to what a requesting peer may hold.
+     *
+     * The document lane serves a tree scoped by read-ACL, but a credential is not
+     * readable by scope: a group co-member holds no wrapping under someone else's
+     * key, so serving them its rows ships ciphertext they can never open and reveals
+     * the key exists. The predicate is recipient-addressed instead. A key's row and
+     * its entry ops travel to any recipient of the key — a peer holding a wrapping
+     * under it. A wrapping's op travels only to the DID it names, so a recipient
+     * never receives a co-recipient's wrapping. Recipient match folds both sides
+     * with `normalizeDID`, because `recipient_did` is stored un-normalized.
+     */
+    listOpsForRequester(requesterDID: string, keyID?: string): Promise<Array<CredentialOp>>;
+    /**
+     * The live (non-tombstoned) subject ids this device holds — keys, wrappings and
+     * entries alike. What a reconcile caller advertises as `held`: the server reads
+     * it to skip rows the caller already has and to route a tombstone for a held id
+     * that is now revoked.
+     */
+    listHeldSubjects(): Promise<Array<HeldCredentialSubject>>;
+};
+export declare function createCredentialStore(db: Kysely<CredentialTables>, adapter: Adapter): CredentialStoreAPI;

package/lib/api.js

@@ -0,0 +1,424 @@
+import { normalizeDID } from '@kokuin/token';
+/**
+ * Run `write` as one atomic unit.
+ *
+ * A row and the op that speaks for it must land together or not at all: a crash
+ * between a delete and its tombstone loses the deletion, and one between a put
+ * and its op leaves a row nothing authenticates. Kysely rejects a nested
+ * `transaction()`, and an ambient one already provides the atomicity, so inside
+ * a caller's transaction the statements run inline.
+ */ async function writeAtomically(db, write) {
+    if (db.isTransaction) {
+        await write(db);
+        return;
+    }
+    await db.transaction().execute(async (tx)=>{
+        await write(tx);
+    });
+}
+const OP_REJECTED = Symbol('credential op rejected');
+async function writeOp(params) {
+    const { db, subjectKind, subjectID, op, deleted, allowKeyMove = false } = params;
+    const values = {
+        subject_kind: subjectKind,
+        subject_id: subjectID,
+        key_id: op.keyID,
+        author_did: op.authorDID,
+        hlc: op.hlc,
+        op_jwt: op.opJWT,
+        op_hash: op.opHash,
+        branch_id: op.branchID,
+        deleted
+    };
+    const result = await db.insertInto('kubun_credential_ops').values(values).onConflict((oc)=>{
+        const update = oc.columns([
+            'subject_kind',
+            'subject_id'
+        ]).doUpdateSet({
+            key_id: values.key_id,
+            author_did: values.author_did,
+            hlc: values.hlc,
+            op_jwt: values.op_jwt,
+            op_hash: values.op_hash,
+            branch_id: values.branch_id,
+            deleted: values.deleted
+        })// Ownership and the LWW comparison live in the conflict statement so
+        // concurrent replicas cannot both pass a preceding read.
+        .where((eb)=>eb.or([
+                eb('kubun_credential_ops.hlc', '<', values.hlc),
+                eb.and([
+                    eb('kubun_credential_ops.hlc', '=', values.hlc),
+                    eb('kubun_credential_ops.op_hash', '<', values.op_hash)
+                ]),
+                eb.and([
+                    eb('kubun_credential_ops.hlc', '=', values.hlc),
+                    eb('kubun_credential_ops.op_hash', '=', values.op_hash),
+                    eb('kubun_credential_ops.deleted', '<=', values.deleted)
+                ])
+            ]));
+        return allowKeyMove ? update : update.where('kubun_credential_ops.key_id', '=', values.key_id);
+    }).executeTakeFirst();
+    return (result.numInsertedOrUpdatedRows ?? 0n) > 0n;
+}
+export function createCredentialStore(db, adapter) {
+    /**
+   * Write a row and its op together, unless a tombstone already covers it.
+   *
+   * A `null` op writes the row on its own: the op is what a writer able to sign
+   * supplies, and nothing here can mint one.
+   */ async function writeSubject(params) {
+        const { subjectKind, subjectID, op, write, accept, allowKeyMove = false } = params;
+        if (op == null) {
+            if (accept == null) {
+                await write(db);
+            } else {
+                await writeAtomically(db, async (tx)=>{
+                    if (await accept(tx)) await write(tx);
+                });
+            }
+            return;
+        }
+        const ownsTransaction = !db.isTransaction;
+        try {
+            await writeAtomically(db, async (tx)=>{
+                if (!await writeOp({
+                    db: tx,
+                    subjectKind,
+                    subjectID,
+                    op,
+                    deleted: 0,
+                    allowKeyMove
+                })) return;
+                // The op conflict serializes concurrent writers before this read. A
+                // rejected version must roll its provisional op update back too.
+                if (accept != null && !await accept(tx)) throw OP_REJECTED;
+                await write(tx);
+            });
+        } catch (error) {
+            if (error === OP_REJECTED && ownsTransaction) return;
+            throw error;
+        }
+    }
+    async function deleteSubject(params) {
+        const { subjectKind, subjectID, tombstone, remove } = params;
+        if (tombstone == null) {
+            await remove(db);
+            return;
+        }
+        await writeAtomically(db, async (tx)=>{
+            if (!await writeOp({
+                db: tx,
+                subjectKind,
+                subjectID,
+                op: tombstone,
+                deleted: 1
+            })) return;
+            await remove(tx);
+        });
+    }
+    async function writeEntry(params, op, allowMove) {
+        const values = {
+            entry_id: params.entryID,
+            key_id: params.keyID,
+            key_version: params.keyVersion,
+            iv: adapter.encodeBinary(params.iv),
+            ciphertext: adapter.encodeBinary(params.ciphertext),
+            hlc: params.hlc
+        };
+        await writeSubject({
+            subjectKind: 'entry',
+            subjectID: params.entryID,
+            op,
+            write: async (tx)=>{
+                if (!allowMove) {
+                    const existing = await tx.selectFrom('kubun_credential_entries').select('key_id').where('entry_id', '=', params.entryID).executeTakeFirst();
+                    if (existing != null && existing.key_id !== params.keyID) {
+                        throw new Error(`Credential entry ${params.entryID} already belongs to key ${existing.key_id}`);
+                    }
+                }
+                const result = await tx.insertInto('kubun_credential_entries').values(values).onConflict((oc)=>{
+                    const update = oc.column('entry_id').doUpdateSet({
+                        key_id: values.key_id,
+                        key_version: values.key_version,
+                        iv: values.iv,
+                        ciphertext: values.ciphertext,
+                        hlc: values.hlc
+                    });
+                    return allowMove ? update : update.where('kubun_credential_entries.key_id', '=', values.key_id);
+                }).executeTakeFirst();
+                if (!allowMove && (result.numInsertedOrUpdatedRows ?? 0n) === 0n) {
+                    throw new Error(`Credential entry ${params.entryID} belongs to another key`);
+                }
+            },
+            allowKeyMove: allowMove
+        });
+    }
+    return {
+        async putKey (params, op) {
+            await writeSubject({
+                subjectKind: 'key',
+                subjectID: params.keyID,
+                op,
+                write: async (tx)=>{
+                    await tx.insertInto('kubun_credential_keys').values({
+                        key_id: params.keyID,
+                        owner_did: params.ownerDID,
+                        suite: params.suite,
+                        version: params.version,
+                        state: params.state
+                    }).onConflict((oc)=>oc.column('key_id').doUpdateSet({
+                            owner_did: params.ownerDID,
+                            suite: params.suite,
+                            version: params.version,
+                            state: params.state
+                        })).execute();
+                },
+                accept: async (tx)=>{
+                    const existing = await tx.selectFrom('kubun_credential_keys').select('version').where('key_id', '=', params.keyID).executeTakeFirst();
+                    return existing == null || params.version >= existing.version;
+                }
+            });
+        },
+        async getKey (keyID) {
+            return await db.selectFrom('kubun_credential_keys').selectAll().where('key_id', '=', keyID).executeTakeFirst();
+        },
+        async listKeys (ownerDID) {
+            return await db.selectFrom('kubun_credential_keys').selectAll().where('owner_did', '=', ownerDID).orderBy('created_at', 'asc').orderBy('key_id', 'asc').execute();
+        },
+        async setKeyState (keyID, state, op) {
+            await writeSubject({
+                subjectKind: 'key',
+                subjectID: keyID,
+                op,
+                write: async (tx)=>{
+                    await tx.updateTable('kubun_credential_keys').set({
+                        state
+                    }).where('key_id', '=', keyID).execute();
+                }
+            });
+        },
+        async setKeyVersion (keyID, version, op) {
+            await writeSubject({
+                subjectKind: 'key',
+                subjectID: keyID,
+                op,
+                write: async (tx)=>{
+                    await tx.updateTable('kubun_credential_keys').set({
+                        version
+                    }).where('key_id', '=', keyID).execute();
+                },
+                accept: async (tx)=>{
+                    const existing = await tx.selectFrom('kubun_credential_keys').select('version').where('key_id', '=', keyID).executeTakeFirst();
+                    return existing == null || version >= existing.version;
+                }
+            });
+        },
+        async deleteKey (keyID, tombstone) {
+            await deleteSubject({
+                subjectKind: 'key',
+                subjectID: keyID,
+                tombstone,
+                remove: async (tx)=>{
+                    await tx.deleteFrom('kubun_credential_keys').where('key_id', '=', keyID).execute();
+                }
+            });
+        },
+        async recordKeyBranch (params) {
+            await db.insertInto('kubun_credential_key_branches').values({
+                key_id: params.keyID,
+                key_version: params.keyVersion,
+                op_hash: params.opHash,
+                author_did: params.authorDID,
+                hlc: params.hlc,
+                op_jwt: params.opJWT,
+                branch_id: params.branchID
+            }).onConflict((oc)=>oc.columns([
+                    'key_id',
+                    'key_version',
+                    'op_hash'
+                ]).doNothing()).execute();
+        },
+        async listKeyBranches (keyID, keyVersion) {
+            return await db.selectFrom('kubun_credential_key_branches').selectAll().where('key_id', '=', keyID).where('key_version', '=', keyVersion).orderBy('branch_id', 'asc').execute();
+        },
+        async putWrapping (params, op) {
+            const values = {
+                wrapping_id: params.wrappingID,
+                key_id: params.keyID,
+                key_version: params.keyVersion,
+                factors: adapter.encodeJSON(params.factors),
+                iv: adapter.encodeBinary(params.iv),
+                wrapped_key: adapter.encodeBinary(params.wrappedKey),
+                recipient_did: params.recipientDID ?? null
+            };
+            await writeSubject({
+                subjectKind: 'wrapping',
+                subjectID: params.wrappingID,
+                op,
+                write: async (tx)=>{
+                    const existing = await tx.selectFrom('kubun_credential_wrappings').select('key_id').where('wrapping_id', '=', params.wrappingID).executeTakeFirst();
+                    if (existing != null && existing.key_id !== params.keyID) {
+                        throw new Error(`Credential wrapping ${params.wrappingID} already belongs to key ${existing.key_id}`);
+                    }
+                    const result = await tx.insertInto('kubun_credential_wrappings').values(values).onConflict((oc)=>oc.column('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
+                        }).where('kubun_credential_wrappings.key_id', '=', values.key_id)).executeTakeFirst();
+                    if ((result.numInsertedOrUpdatedRows ?? 0n) === 0n) {
+                        throw new Error(`Credential wrapping ${params.wrappingID} belongs to another key`);
+                    }
+                }
+            });
+        },
+        async getWrapping (wrappingID) {
+            return await db.selectFrom('kubun_credential_wrappings').selectAll().where('wrapping_id', '=', wrappingID).executeTakeFirst();
+        },
+        async listWrappings (keyID, keyVersion) {
+            let query = db.selectFrom('kubun_credential_wrappings').selectAll().where('key_id', '=', keyID);
+            if (keyVersion != null) {
+                query = query.where('key_version', '=', keyVersion);
+            }
+            return await query.orderBy('created_at', 'asc').orderBy('wrapping_id', 'asc').execute();
+        },
+        async listWrappingsWithBranch (keyID, keyVersion) {
+            // LEFT JOIN so a wrapping with no op row still lists — its branch is the
+            // empty label. The ops PK is `(subject_kind, subject_id)`, so a wrapping
+            // matches at most one op and the join never fans out.
+            let query = db.selectFrom('kubun_credential_wrappings as w').leftJoin('kubun_credential_ops as o', (join)=>join.onRef('o.subject_id', '=', 'w.wrapping_id').on('o.subject_kind', '=', 'wrapping')).selectAll('w').select('o.branch_id as branch_id').where('w.key_id', '=', keyID);
+            if (keyVersion != null) {
+                query = query.where('w.key_version', '=', keyVersion);
+            }
+            const rows = await query.orderBy('w.created_at', 'asc').orderBy('w.wrapping_id', 'asc').execute();
+            return rows.map((row)=>({
+                    ...row,
+                    branch_id: row.branch_id ?? ''
+                }));
+        },
+        async deleteWrapping (wrappingID, tombstone) {
+            await deleteSubject({
+                subjectKind: 'wrapping',
+                subjectID: wrappingID,
+                tombstone,
+                remove: async (tx)=>{
+                    await tx.deleteFrom('kubun_credential_wrappings').where('wrapping_id', '=', wrappingID).execute();
+                }
+            });
+        },
+        async deleteWrappingsBelowVersion (keyID, keyVersion, tombstones) {
+            const remove = async (tx)=>{
+                await tx.deleteFrom('kubun_credential_wrappings').where('key_id', '=', keyID).where('key_version', '<', keyVersion).execute();
+            };
+            if (tombstones == null) {
+                await remove(db);
+                return;
+            }
+            await writeAtomically(db, async (tx)=>{
+                for (const tombstone of tombstones){
+                    if (!await writeOp({
+                        db: tx,
+                        subjectKind: 'wrapping',
+                        subjectID: tombstone.subjectID,
+                        op: tombstone,
+                        deleted: 1
+                    })) {
+                        continue;
+                    }
+                    await tx.deleteFrom('kubun_credential_wrappings').where('wrapping_id', '=', tombstone.subjectID).where('key_id', '=', keyID).where('key_version', '<', keyVersion).execute();
+                }
+            });
+        },
+        async putEntry (params, op) {
+            await writeEntry(params, op, false);
+        },
+        async moveEntry (params, op) {
+            await writeEntry(params, op, true);
+        },
+        async getEntry (entryID) {
+            return await db.selectFrom('kubun_credential_entries').selectAll().where('entry_id', '=', entryID).executeTakeFirst();
+        },
+        async getEntryWithProvenance (entryID) {
+            return await db.selectFrom('kubun_credential_entries as e').leftJoin('kubun_credential_ops as o', (join)=>join.onRef('o.subject_id', '=', 'e.entry_id').on('o.subject_kind', '=', 'entry')).selectAll('e').select('o.author_did as author_did').where('e.entry_id', '=', entryID).executeTakeFirst();
+        },
+        async listEntries (keyID) {
+            return await db.selectFrom('kubun_credential_entries').selectAll().where('key_id', '=', keyID).orderBy('created_at', 'asc').orderBy('entry_id', 'asc').execute();
+        },
+        async deleteEntry (entryID, tombstone) {
+            await deleteSubject({
+                subjectKind: 'entry',
+                subjectID: entryID,
+                tombstone,
+                remove: async (tx)=>{
+                    await tx.deleteFrom('kubun_credential_entries').where('entry_id', '=', entryID).execute();
+                }
+            });
+        },
+        async getMaxEntryHLC () {
+            const row = await db.selectFrom('kubun_credential_entries').select((eb)=>eb.fn.max('hlc').as('max_hlc')).executeTakeFirst();
+            return row?.max_hlc ?? null;
+        },
+        async getOp (subjectKind, subjectID) {
+            return await db.selectFrom('kubun_credential_ops').selectAll().where('subject_kind', '=', subjectKind).where('subject_id', '=', subjectID).executeTakeFirst();
+        },
+        async listOps (keyID) {
+            return await scanOps(db, keyID);
+        },
+        async listOpsForRequester (rawRequesterDID, keyID) {
+            const requesterDID = normalizeDID(rawRequesterDID);
+            // Recipient membership comes from the wrappings table, not the ops table: a
+            // rotation deletes a superseded wrapping's row but keeps its tombstone, and
+            // a former recipient of an opens-nothing wrapping is no longer a recipient.
+            // recipient_did is stored un-normalized, so fold at the compare.
+            const wrappings = await db.selectFrom('kubun_credential_wrappings').select([
+                'wrapping_id',
+                'key_id',
+                'recipient_did'
+            ]).where('recipient_did', 'is not', null).execute();
+            const recipientKeyIDs = new Set();
+            const requesterWrappingIDs = new Set();
+            for (const wrapping of wrappings){
+                if (wrapping.recipient_did != null && normalizeDID(wrapping.recipient_did) === requesterDID) {
+                    recipientKeyIDs.add(wrapping.key_id);
+                    requesterWrappingIDs.add(wrapping.wrapping_id);
+                }
+            }
+            const ops = await scanOps(db, keyID);
+            // A wrapping's ciphertext is usable only by its addressee, so its op travels
+            // only to the DID it names — a co-recipient's wrapping stays withheld. A
+            // key's row and its entries travel to any recipient of the key. A wrapping
+            // tombstone names no addressee once its row is gone, so it cannot route
+            // here; revocation propagation is a separate concern.
+            return ops.filter((op)=>{
+                if (op.subject_kind === 'wrapping') {
+                    return requesterWrappingIDs.has(op.subject_id);
+                }
+                return recipientKeyIDs.has(op.key_id);
+            });
+        },
+        async listHeldSubjects () {
+            const rows = await db.selectFrom('kubun_credential_ops').select([
+                'subject_kind',
+                'subject_id',
+                'op_hash'
+            ]).where('deleted', '=', 0).execute();
+            return rows.map((row)=>({
+                    subjectKind: row.subject_kind,
+                    subjectID: row.subject_id,
+                    opHash: row.op_hash
+                }));
+        }
+    };
+}
+/**
+ * The ops leaf scan in stamp order — every one, or one key's. Two devices must
+ * agree on this order, so it cannot be the insertion order, which is local.
+ */ async function scanOps(db, keyID) {
+    let query = db.selectFrom('kubun_credential_ops').selectAll();
+    if (keyID != null) {
+        query = query.where('key_id', '=', keyID);
+    }
+    return await query.orderBy('hlc', 'asc').orderBy('subject_id', 'asc').execute();
+}

package/lib/definition.d.ts

@@ -0,0 +1,4 @@
+import type { StoreDefinition } from '@kubun/db';
+import type { CredentialStoreAPI } from './api.js';
+import type { CredentialTables } from './tables.js';
+export declare const credentialStoreDefinition: StoreDefinition<CredentialTables, CredentialStoreAPI>;

package/lib/definition.js

@@ -0,0 +1,7 @@
+import { createCredentialStore } from './api.js';
+import { getCredentialMigrations } from './migrations.js';
+export const credentialStoreDefinition = {
+    name: 'credential',
+    migrations: getCredentialMigrations,
+    createAPI: createCredentialStore
+};

package/lib/index.d.ts

@@ -0,0 +1,8 @@
+import type { StoreProvider } from '@kubun/db';
+import type { CredentialStoreAPI } from './api.js';
+export type { CredentialOpInput, CredentialStoreAPI, CredentialTombstoneInput, HeldCredentialSubject, PutCredentialEntryParams, PutCredentialKeyParams, PutCredentialWrappingParams, } from './api.js';
+export { createCredentialStore } from './api.js';
+export { credentialStoreDefinition } from './definition.js';
+export declare const CREDENTIAL_STORE: "credential";
+export declare function getCredentialStore(provider: StoreProvider): Promise<CredentialStoreAPI>;
+export type { CredentialEntry, CredentialEntryTable, CredentialEntryWithProvenance, CredentialFactorDescriptor, CredentialKey, CredentialKeyBranch, CredentialKeyBranchTable, CredentialKeyState, CredentialKeyTable, CredentialOp, CredentialOpSubjectKind, CredentialOpTable, CredentialTables, CredentialWrapping, CredentialWrappingTable, CredentialWrappingWithBranch, InsertCredentialEntry, InsertCredentialKey, InsertCredentialOp, InsertCredentialWrapping, } from './tables.js';

package/lib/index.js

@@ -0,0 +1,6 @@
+export { createCredentialStore } from './api.js';
+export { credentialStoreDefinition } from './definition.js';
+export const CREDENTIAL_STORE = 'credential';
+export function getCredentialStore(provider) {
+    return provider.getStore(CREDENTIAL_STORE);
+}

package/lib/migrations.d.ts

@@ -0,0 +1,3 @@
+import type { MigrationContext } from '@kubun/db';
+import type { Migration } from 'kysely/migration';
+export declare function getCredentialMigrations(ctx: MigrationContext): Record<string, Migration>;

package/lib/migrations.js

@@ -0,0 +1,57 @@
+export function getCredentialMigrations(ctx) {
+    const t = ctx.types;
+    const now = ctx.functions.now;
+    const init = {
+        async up (db) {
+            // Credential keys: public record only, no key material.
+            await db.schema.createTable('kubun_credential_keys').ifNotExists().addColumn('key_id', t.text, (col)=>col.notNull().primaryKey()).addColumn('owner_did', t.text, (col)=>col.notNull()).addColumn('suite', 'integer', (col)=>col.notNull()).addColumn('version', 'integer', (col)=>col.notNull()).addColumn('state', t.text, (col)=>col.notNull()).addColumn('created_at', t.timestamp, (col)=>col.defaultTo(now).notNull()).execute();
+            // Key-op history is retained so a branch label can be re-authenticated.
+            await db.schema.createTable('kubun_credential_key_branches').ifNotExists().addColumn('key_id', t.text, (col)=>col.notNull()).addColumn('key_version', 'integer', (col)=>col.notNull()).addColumn('op_hash', t.text, (col)=>col.notNull()).addColumn('author_did', t.text, (col)=>col.notNull()).addColumn('hlc', t.text, (col)=>col.notNull()).addColumn('op_jwt', t.text, (col)=>col.notNull()).addColumn('branch_id', t.text, (col)=>col.notNull()).addColumn('created_at', t.timestamp, (col)=>col.defaultTo(now).notNull()).addPrimaryKeyConstraint('pk_kubun_credential_key_branches', [
+                'key_id',
+                'key_version',
+                'op_hash'
+            ]).execute();
+            // Wrappings: one row per way of opening one version of one key. Keyed on
+            // its own id rather than (key, recipient) — a key can carry several
+            // wrappings for the same recipient, differing in their factor lists.
+            await db.schema.createTable('kubun_credential_wrappings').ifNotExists().addColumn('wrapping_id', t.text, (col)=>col.notNull().primaryKey()).addColumn('key_id', t.text, (col)=>col.notNull()).addColumn('key_version', 'integer', (col)=>col.notNull()).addColumn('factors', t.json, (col)=>col.notNull()).addColumn('iv', t.binary, (col)=>col.notNull()).addColumn('wrapped_key', t.binary, (col)=>col.notNull()).addColumn('recipient_did', t.text).addColumn('created_at', t.timestamp, (col)=>col.defaultTo(now).notNull()).execute();
+            await db.schema.createIndex('idx_kubun_credential_wrappings_key').ifNotExists().on('kubun_credential_wrappings').columns([
+                'key_id',
+                'key_version'
+            ]).execute();
+            // Entries: opaque ciphertext under a key version.
+            await db.schema.createTable('kubun_credential_entries').ifNotExists().addColumn('entry_id', t.text, (col)=>col.notNull().primaryKey()).addColumn('key_id', t.text, (col)=>col.notNull()).addColumn('key_version', 'integer', (col)=>col.notNull()).addColumn('iv', t.binary, (col)=>col.notNull()).addColumn('ciphertext', t.binary, (col)=>col.notNull()).addColumn('hlc', t.text, (col)=>col.notNull()).addColumn('created_at', t.timestamp, (col)=>col.defaultTo(now).notNull()).execute();
+            await db.schema.createIndex('idx_kubun_credential_entries_key').ifNotExists().on('kubun_credential_entries').columns([
+                'key_id'
+            ]).execute();
+            // Ops: the latest signed op per subject, and the only place a deletion is
+            // recorded. Keyed on (kind, id) rather than on the subject id alone —
+            // nothing guarantees a key id cannot equal an entry id, and a collision
+            // would let one subject's op tombstone another's.
+            await db.schema.createTable('kubun_credential_ops').ifNotExists().addColumn('subject_kind', t.text, (col)=>col.notNull()).addColumn('subject_id', t.text, (col)=>col.notNull()).addColumn('key_id', t.text, (col)=>col.notNull()).addColumn('author_did', t.text, (col)=>col.notNull()).addColumn('hlc', t.text, (col)=>col.notNull()).addColumn('op_jwt', t.text, (col)=>col.notNull()).addColumn('op_hash', t.text, (col)=>col.notNull())// The content-key branch this op joins. No index yet: partitioning by
+            // branch is a later slice, and the merkle scan still orders by hlc.
+            .addColumn('branch_id', t.text, (col)=>col.notNull().defaultTo('')).addColumn('deleted', 'integer', (col)=>col.notNull().defaultTo(0)).addColumn('created_at', t.timestamp, (col)=>col.defaultTo(now).notNull()).addPrimaryKeyConstraint('pk_kubun_credential_ops', [
+                'subject_kind',
+                'subject_id'
+            ]).execute();
+            await db.schema.createIndex('idx_kubun_credential_ops_key').ifNotExists().on('kubun_credential_ops').columns([
+                'key_id'
+            ]).execute();
+            // The merkle lane buckets leaves by time and reads them in stamp order, so
+            // the scan that builds a tree is this index rather than a sort of the table.
+            await db.schema.createIndex('idx_kubun_credential_ops_hlc').ifNotExists().on('kubun_credential_ops').columns([
+                'hlc'
+            ]).execute();
+        },
+        async down (db) {
+            await db.schema.dropTable('kubun_credential_ops').ifExists().execute();
+            await db.schema.dropTable('kubun_credential_entries').ifExists().execute();
+            await db.schema.dropTable('kubun_credential_wrappings').ifExists().execute();
+            await db.schema.dropTable('kubun_credential_key_branches').ifExists().execute();
+            await db.schema.dropTable('kubun_credential_keys').ifExists().execute();
+        }
+    };
+    return {
+        '0-init': init
+    };
+}

package/lib/tables.d.ts

@@ -0,0 +1,158 @@
+import type { CreatedAtColumn } from '@kubun/db-adapter';
+import type { ColumnType, Insertable, Selectable } from 'kysely';
+type JSONArrayColumn<T> = ColumnType<Array<T>, Array<T> | undefined, Array<T>>;
+type DefaultedNumberColumn = ColumnType<number, number | undefined, number>;
+/**
+ * Whether a key is the one new entries encrypt under.
+ *
+ * `retired` is not `deleted`: a rotation bumps the version and leaves the old
+ * one readable, because entries written under it still exist. Dropping the row
+ * would make them undecryptable rather than stale.
+ */
+export type CredentialKeyState = 'active' | 'retired';
+/**
+ * One factor in a wrapping's ordered AND-list. `params` is per-kind public
+ * material — an ephemeral public key for `did`, an Argon2 salt and cost
+ * parameters for `passphrase` and `pin`. Never a secret.
+ */
+export type CredentialFactorDescriptor = {
+    kind: string;
+    params: Record<string, unknown>;
+};
+/**
+ * A content key's public record. Carries no key material of any kind: the key
+ * itself exists only inside wrappings, and only as ciphertext.
+ */
+export type CredentialKeyTable = {
+    key_id: string;
+    owner_did: string;
+    suite: number;
+    version: number;
+    state: string;
+    created_at: CreatedAtColumn;
+};
+export type CredentialKey = Selectable<CredentialKeyTable>;
+export type InsertCredentialKey = Insertable<CredentialKeyTable>;
+/** An authenticated key-op retained as append-only branch provenance. */
+export type CredentialKeyBranchTable = {
+    key_id: string;
+    key_version: number;
+    op_hash: string;
+    author_did: string;
+    hlc: string;
+    op_jwt: string;
+    branch_id: string;
+    created_at: CreatedAtColumn;
+};
+export type CredentialKeyBranch = Selectable<CredentialKeyBranchTable>;
+/**
+ * One way to open one version of one key.
+ *
+ * `factors` is ORDERED and the order is significant — the KEK derivation
+ * concatenates the factor secrets, so reordering produces a different key. It is
+ * also covered by the wrapping's AAD, which is what makes a tampered descriptor
+ * distinguishable from a wrong secret.
+ *
+ * `recipient_did` holds a peer:4 DID. It is an input to key resolution, not an
+ * identity for comparison: callers accept either long or short form and resolve
+ * the current long-form document before opening. Anything comparing this to a
+ * roster DID must normalize at the comparison.
+ *
+ * `iv` is its own column rather than a prefix on `wrapped_key`, matching entries.
+ * A wrapping is not a single self-contained blob under either framing — `factors`
+ * is bound into its AAD, so a recipient without the descriptors cannot open it
+ * regardless.
+ */
+export type CredentialWrappingTable = {
+    wrapping_id: string;
+    key_id: string;
+    key_version: number;
+    factors: JSONArrayColumn<CredentialFactorDescriptor>;
+    iv: Uint8Array;
+    wrapped_key: Uint8Array;
+    recipient_did: string | null;
+    created_at: CreatedAtColumn;
+};
+export type CredentialWrapping = Selectable<CredentialWrappingTable>;
+export type InsertCredentialWrapping = Insertable<CredentialWrappingTable>;
+/**
+ * A wrapping paired with the branch label of its op, for the fork-aware read
+ * path. Empty label when no op row exists — a branch-agnostic wrapping, not a
+ * branch of its own.
+ */
+export type CredentialWrappingWithBranch = CredentialWrapping & {
+    branch_id: string;
+};
+/**
+ * One encrypted value. The plaintext's shape is application-defined and the
+ * store never parses it — not as JSON, not as UTF-8, not at all.
+ *
+ * `key_version` is stored per entry rather than read from the key: a rotation
+ * moves the key forward while entries written under the old version stay
+ * readable, and the version is what selects the wrapping that opens them.
+ */
+export type CredentialEntryTable = {
+    entry_id: string;
+    key_id: string;
+    key_version: number;
+    iv: Uint8Array;
+    ciphertext: Uint8Array;
+    hlc: string;
+    created_at: CreatedAtColumn;
+};
+export type CredentialEntry = Selectable<CredentialEntryTable>;
+export type InsertCredentialEntry = Insertable<CredentialEntryTable>;
+export type CredentialEntryWithProvenance = CredentialEntry & {
+    author_did: string | null;
+};
+/** Which of the three tables a signed op speaks for. */
+export type CredentialOpSubjectKind = 'key' | 'wrapping' | 'entry';
+/**
+ * The latest signed op for one key, wrapping or entry — replaced on update, not
+ * appended. There is no op history: a credential op is a whole-row replacement,
+ * and a log would retain the wrapped key and the ciphertext that a rotation
+ * exists to destroy.
+ *
+ * One table for all three subjects because a merkle tree wants its leaves from
+ * one scan rather than a union, and because a deletion has to travel: a lane
+ * that only adds cannot express absence, so a delete leaves a row here with
+ * `deleted` set and removes nothing else.
+ *
+ * `deleted` is an integer 0/1 rather than a boolean so it reads back identically
+ * on SQLite and Postgres, matching the other flags in this stack.
+ *
+ * `hlc` is the op author's stamp, not the local write time. For an entry it is
+ * the same string the entry row carries — the two must agree, and a test pins
+ * that.
+ */
+export type CredentialOpTable = {
+    subject_kind: string;
+    subject_id: string;
+    /** So a whole vault can be served, swept or dropped together. */
+    key_id: string;
+    /** The op's verified issuer, normalized — this one IS compared. */
+    author_did: string;
+    hlc: string;
+    op_jwt: string;
+    /** Digest of `op_jwt`, as the graph mutation log addresses its mutations. */
+    op_hash: string;
+    /**
+     * Which content-key branch this op belongs to, `${hlc}:${opHash}` of the
+     * key-op that introduced the branch. A keyless party partitions and ranks
+     * branches by this without holding a wrapping. Empty for an op minted outside
+     * a rotation/create, which does not yet resolve the branch it joins.
+     */
+    branch_id: string;
+    deleted: DefaultedNumberColumn;
+    created_at: CreatedAtColumn;
+};
+export type CredentialOp = Selectable<CredentialOpTable>;
+export type InsertCredentialOp = Insertable<CredentialOpTable>;
+export type CredentialTables = {
+    kubun_credential_keys: CredentialKeyTable;
+    kubun_credential_key_branches: CredentialKeyBranchTable;
+    kubun_credential_wrappings: CredentialWrappingTable;
+    kubun_credential_entries: CredentialEntryTable;
+    kubun_credential_ops: CredentialOpTable;
+};
+export {};

package/lib/tables.js

@@ -0,0 +1,2 @@
+// --- Aggregate CredentialTables type ---
+export { };

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@kubun/store-credential",
+  "version": "0.13.0",
+  "keywords": [],
+  "license": "see LICENSE.md",
+  "sideEffects": false,
+  "type": "module",
+  "exports": {
+    ".": "./lib/index.js"
+  },
+  "main": "lib/index.js",
+  "types": "lib/index.d.ts",
+  "files": [
+    "lib/*",
+    "LICENSE.md"
+  ],
+  "dependencies": {
+    "@kokuin/token": "^0.5.0",
+    "kysely": "^0.29.5",
+    "@kubun/db": "^0.13.0",
+    "@kubun/db-adapter": "^0.13.0"
+  },
+  "devDependencies": {
+    "@testcontainers/postgresql": "^12.1.0",
+    "@kubun/db-postgres": "^0.13.0",
+    "@kubun/db-better-sqlite": "^0.13.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "pnpm run build:clean && pnpm run build:js && pnpm run build:types",
+    "build:clean": "del lib",
+    "build:js": "swc src -d ./lib --config-file ../../node_modules/@kigu/dev/swc.json --strip-leading-paths",
+    "build:types": "tsc --emitDeclarationOnly --skipLibCheck",
+    "build:types:ci": "tsc --emitDeclarationOnly --declarationMap false",
+    "test": "pnpm run test:types && pnpm run test:unit",
+    "test:types": "tsc --noEmit -p tsconfig.test.json",
+    "test:unit": "vitest run"
+  }
+}