@kubun/store-credential 0.17.3 → 0.18.0

package/lib/store-context.d.ts

@@ -0,0 +1,37 @@
+import { type Adapter } from '@kubun/db-adapter';
+import { type Kysely } from 'kysely';
+import type { CredentialStoreAPI } from './api-types.js';
+import type { VerifiedRecordCopies } from './records.js';
+import type { CredentialTables } from './tables.js';
+export type StoreContext = {
+    db: Kysely<CredentialTables>;
+    adapter: Adapter;
+    advisoryIDForKey?: (keyID: string) => bigint | Promise<bigint>;
+    api: () => CredentialStoreAPI;
+    verifiedCopies: VerifiedRecordCopies;
+    oneOwner: <T extends {
+        owner_did: string;
+    }>(rows: Array<T>, address: string) => Array<T>;
+    ownerForKey: (keyID: string, ownerDID?: string) => Promise<string>;
+    lockKeyRowInTransaction: (tx: Kysely<CredentialTables>, keyID: string) => Promise<void>;
+    lockKeyRowsInTransaction: (tx: Kysely<CredentialTables>, keyIDs: ReadonlyArray<string>) => Promise<void>;
+    writeSubject: (params: {
+        keyID: string;
+        keyIDs?: Array<string>;
+        write: (tx: Kysely<CredentialTables>) => Promise<void>;
+        accept?: (tx: Kysely<CredentialTables>) => Promise<boolean>;
+    }) => Promise<void>;
+    deleteSubject: (params: {
+        keyID: string;
+        remove: (tx: Kysely<CredentialTables>) => Promise<void>;
+    }) => Promise<void>;
+    writeAmbient: (innerDb: Kysely<CredentialTables>, write: (tx: Kysely<CredentialTables>) => Promise<void>) => Promise<void>;
+    gatedIfAmbient: <T>(fn: () => Promise<T>) => Promise<T>;
+};
+export type StoreContextParams = {
+    db: Kysely<CredentialTables>;
+    adapter: Adapter;
+    advisoryIDForKey: ((keyID: string) => bigint | Promise<bigint>) | undefined;
+    getAPI: () => CredentialStoreAPI;
+};
+export declare function createStoreContext(params: StoreContextParams): StoreContext;

package/lib/store-context.js

@@ -0,0 +1,139 @@
+import { AbstractPostgresAdapter } from '@kubun/db-adapter';
+import { sql } from 'kysely';
+import { orderAdvisoryLockIDs } from './advisory-locks.js';
+/**
+ * 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);
+    });
+}
+export function createStoreContext(params) {
+    const { db, adapter, advisoryIDForKey, getAPI } = params;
+    const verifiedCopies = new Map();
+    function oneOwner(rows, address) {
+        if (new Set(rows.map((row)=>row.owner_did)).size > 1) {
+            throw new Error(`Credential ${address} needs an owner`);
+        }
+        return rows;
+    }
+    async function ownerForKey(keyID, ownerDID) {
+        if (ownerDID !== undefined) return ownerDID;
+        const owners = new Set();
+        for (const table of [
+            'kubun_credential_keys',
+            'kubun_credential_key_branches',
+            'kubun_credential_wrappings',
+            'kubun_credential_entries',
+            'kubun_credential_entry_candidates',
+            'kubun_credential_revocations',
+            'kubun_credential_key_owner_delegation'
+        ]){
+            const rows = await db.selectFrom(table).select('owner_did').where('key_id', '=', keyID).execute();
+            for (const row of rows)owners.add(row.owner_did);
+            if (owners.size > 1) throw new Error(`Credential key ${keyID} needs an owner`);
+        }
+        // Legacy local rows can precede a key row; they live in the empty local namespace.
+        return owners.values().next().value ?? '';
+    }
+    async function lockKeyRowsInTransaction(tx, keyIDs) {
+        if (!tx.isTransaction) throw new Error('lockKeyRows requires a store transaction');
+        const keys = [
+            ...new Set(keyIDs)
+        ];
+        if (keys.length === 0) return;
+        if (adapter instanceof AbstractPostgresAdapter) {
+            // A row lock cannot protect a key before its first insert. The first 64
+            // MD5 bits give every transaction the same lock for present and absent keys.
+            // Hash every key before locking so colliding IDs are deduplicated and all
+            // transactions acquire their IDs in the same signed numeric order.
+            const keyedIDs = [];
+            for (const keyID of keys){
+                const advisoryID = advisoryIDForKey == null ? BigInt((await sql`SELECT (('x' || md5(${`credential-key:${keyID}`}::text))::bit(64)::bigint)::text AS lock_id`.execute(tx)).rows[0]?.lock_id ?? '') : await advisoryIDForKey(keyID);
+                keyedIDs.push({
+                    keyID,
+                    advisoryID
+                });
+            }
+            for (const advisoryID of orderAdvisoryLockIDs(keyedIDs)){
+                await sql`SELECT pg_advisory_xact_lock(${advisoryID.toString()}::bigint)`.execute(tx);
+            }
+        } else {
+            // SQLite's deferred BEGIN does not reserve its single writer until a
+            // write. Acquire it before the first read, matching Postgres ordering.
+            await tx.updateTable('kubun_credential_keys').set((eb)=>({
+                    version: eb.ref('kubun_credential_keys.version')
+                })).where('key_id', 'in', keys).executeTakeFirst();
+        }
+    }
+    async function lockKeyRowInTransaction(tx, keyID) {
+        await lockKeyRowsInTransaction(tx, [
+            keyID
+        ]);
+    }
+    async function writeSubject(params) {
+        await writeAmbient(db, async (tx)=>{
+            await lockKeyRowsInTransaction(tx, params.keyIDs ?? [
+                params.keyID
+            ]);
+            if (params.accept == null || await params.accept(tx)) await params.write(tx);
+        });
+    }
+    async function deleteSubject(params) {
+        await writeAmbient(db, async (tx)=>{
+            await lockKeyRowInTransaction(tx, params.keyID);
+            await params.remove(tx);
+        });
+    }
+    // One async gate serializes EVERY write that joins a caller-supplied ambient
+    // transaction.
+    // then holds the connection exclusively for its
+    // whole open → rollback/release window, so a ROLLBACK TO SAVEPOINT can never undo
+    // another concurrent write's committed work — a savepoint rollback reverts ALL work
+    // since the savepoint, not just this operation's statements. getStates resolves its
+    // connectors with Promise.all over one shared request tx, the source of that
+    // concurrency. The gate covers not only the savepoint sections but every ambient
+    // write (writeAmbient, and the raw alias writers via gatedIfAmbient), so no ungated
+    // statement can land inside a savepoint window. Reads are never gated. Owned
+    // transactions (db.isTransaction === false) open their own connection and are
+    // serialized by the driver, so they skip the gate. The gate is per api instance:
+    // `db.isTransaction` is fixed per instance, so a fresh transaction builds a fresh
+    // store with its own gate.
+    let ambientWriteChain = Promise.resolve();
+    const withAmbientWrite = (fn)=>{
+        const run = ambientWriteChain.then(fn, fn);
+        ambientWriteChain = run.then(()=>undefined, ()=>undefined);
+        return run;
+    };
+    // Gate a single raw ambient statement; run it directly when this store owns no
+    // ambient transaction (nothing else can interleave a savepoint there).
+    const gatedIfAmbient = (fn)=>db.isTransaction ? withAmbientWrite(fn) : fn();
+    // writeAtomically, but the inline (ambient) branch runs under the gate so it cannot
+    // interleave a concurrent savepoint section. The owned branch opens its own tx.
+    const writeAmbient = (innerDb, write)=>innerDb.isTransaction ? withAmbientWrite(()=>writeAtomically(innerDb, write)) : writeAtomically(innerDb, write);
+    return {
+        db,
+        adapter,
+        advisoryIDForKey,
+        api: getAPI,
+        verifiedCopies,
+        oneOwner,
+        ownerForKey,
+        lockKeyRowInTransaction,
+        lockKeyRowsInTransaction,
+        writeSubject,
+        deleteSubject,
+        writeAmbient,
+        gatedIfAmbient
+    };
+}

package/lib/tables.d.ts

@@ -1,7 +1,12 @@
 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>;
+/**
+ * The content-key branch a wrapping or entry joins: its introducing key op's
+ * `${hlc}:${opHash}` label, taken from the op that wrote the row. Empty when no op
+ * named one, which readers treat as branch-agnostic.
+ */
+type BranchColumn = ColumnType<string, string | undefined, string>;
 /**
  * Whether a key is the one new entries encrypt under.
  *
@@ -35,6 +40,7 @@ export type CredentialKey = Selectable<CredentialKeyTable>;
 export type InsertCredentialKey = Insertable<CredentialKeyTable>;
 /** An authenticated key-op retained as append-only branch provenance. */
 export type CredentialKeyBranchTable = {
+    owner_did: string;
     key_id: string;
     key_version: number;
     op_hash: string;
@@ -64,6 +70,7 @@ export type CredentialKeyBranch = Selectable<CredentialKeyBranchTable>;
  * regardless.
  */
 export type CredentialWrappingTable = {
+    owner_did: string;
     wrapping_id: string;
     key_id: string;
     key_version: number;
@@ -71,6 +78,7 @@ export type CredentialWrappingTable = {
     iv: Uint8Array;
     wrapped_key: Uint8Array;
     recipient_did: string | null;
+    branch_id: BranchColumn;
     created_at: CreatedAtColumn;
 };
 export type CredentialWrapping = Selectable<CredentialWrappingTable>;
@@ -92,12 +100,14 @@ export type CredentialWrappingWithBranch = CredentialWrapping & {
  * readable, and the version is what selects the wrapping that opens them.
  */
 export type CredentialEntryTable = {
+    owner_did: string;
     entry_id: string;
     key_id: string;
     key_version: number;
     iv: Uint8Array;
     ciphertext: Uint8Array;
     hlc: string;
+    branch_id: BranchColumn;
     created_at: CreatedAtColumn;
 };
 export type CredentialEntry = Selectable<CredentialEntryTable>;
@@ -105,67 +115,6 @@ 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>;
-/**
- * A local pointer from an opaque `(namespace, key)` to the entry id it
- * currently names. Not an op subject: it carries no `hlc` and never appears in
- * `kubun_credential_ops` or the merkle scan, because it is a per-device index
- * rather than a replicated fact — each device that resolves the same
- * `(namespace, key)` points it at the entry it converges on locally.
- *
- * The store does not interpret `namespace`, `alias_key` or `entry_id` — they
- * are stored and returned verbatim, whatever a caller passes.
- */
-export type KubunCredentialAliasTable = {
-    namespace: string;
-    alias_key: string;
-    entry_id: string;
-    created_at: CreatedAtColumn;
-};
-export type CredentialAlias = Selectable<KubunCredentialAliasTable>;
-export type InsertCredentialAlias = Insertable<KubunCredentialAliasTable>;
 /**
  * The grantor-authority envelope backing one wrapping — a signed token proving
  * whoever minted the wrapping held the right to grant it, carried beside it
@@ -173,6 +122,7 @@ export type InsertCredentialAlias = Insertable<KubunCredentialAliasTable>;
  * every `put` strictly-greater, so a stale/replayed envelope is a silent no-op.
  */
 export type CredentialWrappingAuthorityTable = {
+    owner_did: string;
     wrapping_id: string;
     authority_token: string;
     refresh_seq: number;
@@ -267,6 +217,7 @@ export type InsertCredentialManifest = Insertable<CredentialManifestTable>;
  * shape as {@link CredentialWrappingAuthorityTable}.
  */
 export type CredentialKeyOwnerDelegationTable = {
+    owner_did: string;
     key_id: string;
     delegation_tokens: JSONArrayColumn<string>;
     refresh_seq: number;
@@ -274,13 +225,82 @@ export type CredentialKeyOwnerDelegationTable = {
 };
 export type CredentialKeyOwnerDelegation = Selectable<CredentialKeyOwnerDelegationTable>;
 export type InsertCredentialKeyOwnerDelegation = Insertable<CredentialKeyOwnerDelegationTable>;
+type JSONObjectColumn = ColumnType<Record<string, unknown>, Record<string, unknown> | string, Record<string, unknown> | string>;
+/**
+ * A signed copy of the selected owner-qualified credential decision, addressed by
+ * `(type, owner, id, op_hash)`, tombstones included. A deleted record stays with no payload, so an
+ * older write cannot come back.
+ *
+ * The indexed tables (keys, key branches, wrappings, wrapping authority, entries, manifests,
+ * revocations) are projections of the live rows here, written in the same transaction. A
+ * row the legacy verbs wrote into an indexed table has no row here: it is local state that
+ * no record speaks for, and the record lane never lists it.
+ *
+ * `owner`, `hlc`, `payload_digest`, `deleted` and `meta` repeat fields of the claim that
+ * `op_jwt` signs, so the table can be indexed without verifying a token. `payload` is the
+ * exact byte string the claim's digest covers. `deleted` is an integer 0/1 so it reads back
+ * identically on SQLite and Postgres.
+ */
+export type CredentialRecordTable = {
+    type: string;
+    id: string;
+    owner: string;
+    hlc: string;
+    op_jwt: string;
+    op_hash: string;
+    payload_digest: string | null;
+    payload: Uint8Array | null;
+    deleted: number;
+    meta: JSONObjectColumn;
+    created_at: CreatedAtColumn;
+};
+export type CredentialRecordRow = Selectable<CredentialRecordTable>;
+/** Signed entry operations retained per branch for fork comparison and repair. */
+export type CredentialEntryCandidateTable = {
+    owner_did: string;
+    key_id: string;
+    key_version: number;
+    branch_id: string;
+    entry_id: string;
+    owner: string;
+    hlc: string;
+    op_jwt: string;
+    op_hash: string;
+    payload: Uint8Array | null;
+    created_at: CreatedAtColumn;
+};
+/**
+ * A recipient revoked from a key, projected from a `credential.revocation` record. Keyed by
+ * `(key_id, recipient_did)` with the recipient normalized. Only a revocation record writes
+ * here: removing a wrapping, as rotation cleanup does, never touches it, which is what lets
+ * a revocation be told apart from cleanup after replicas merge.
+ */
+export type CredentialRevocationTable = {
+    key_id: string;
+    recipient_did: string;
+    owner_did: string;
+    created_at: CreatedAtColumn;
+};
+export type CredentialRevocation = Selectable<CredentialRevocationTable>;
+/**
+ * A local pointer from `(provider, owner, device)` to the entry holding that device's own
+ * grant. Like the two-key alias it is a per-device index, not a replicated fact, and the
+ * store stores and returns its values verbatim: a caller normalizes the DIDs.
+ */
+export type CredentialDeviceAliasTable = {
+    provider_name: string;
+    owner_did: string;
+    device_did: string;
+    entry_id: string;
+    entry_owner_did: string;
+    created_at: CreatedAtColumn;
+};
+export type CredentialDeviceAlias = Selectable<CredentialDeviceAliasTable>;
 export type CredentialTables = {
     kubun_credential_keys: CredentialKeyTable;
     kubun_credential_key_branches: CredentialKeyBranchTable;
     kubun_credential_wrappings: CredentialWrappingTable;
     kubun_credential_entries: CredentialEntryTable;
-    kubun_credential_ops: CredentialOpTable;
-    kubun_credential_aliases: KubunCredentialAliasTable;
     kubun_credential_wrapping_authority: CredentialWrappingAuthorityTable;
     kubun_credential_grantor_counters: CredentialGrantorCounterTable;
     kubun_credential_provisioning_epochs: CredentialProvisioningEpochTable;
@@ -288,5 +308,9 @@ export type CredentialTables = {
     kubun_credential_provisioning_attempts: CredentialProvisioningAttemptTable;
     kubun_credential_manifests: CredentialManifestTable;
     kubun_credential_key_owner_delegation: CredentialKeyOwnerDelegationTable;
+    kubun_credential_records: CredentialRecordTable;
+    kubun_credential_entry_candidates: CredentialEntryCandidateTable;
+    kubun_credential_revocations: CredentialRevocationTable;
+    kubun_credential_device_aliases: CredentialDeviceAliasTable;
 };
 export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kubun/store-credential",
-  "version": "0.17.3",
+  "version": "0.18.0",
   "keywords": [],
   "license": "see LICENSE.md",
   "sideEffects": false,
@@ -15,15 +15,18 @@
     "LICENSE.md"
   ],
   "dependencies": {
-    "@kokuin/token": "^0.5.0",
-    "@kubun/db": "^0.17.0",
-    "@kubun/db-adapter": "^0.17.0",
-    "kysely": "^0.29.6"
+    "@kokuin/token": "^0.5.1",
+    "@kubun/db": "^0.18.0",
+    "@kubun/db-adapter": "^0.18.0",
+    "@kubun/records": "^0.18.0",
+    "@sozai/codec": "^0.4.3",
+    "kysely": "^0.29.7"
   },
   "devDependencies": {
-    "@kubun/db-better-sqlite": "^0.17.0",
-    "@kubun/db-postgres": "^0.17.1",
-    "@testcontainers/postgresql": "^12.1.0"
+    "@kubun/db-better-sqlite": "^0.18.0",
+    "@kubun/db-postgres": "^0.18.0",
+    "@kubun/hlc": "^0.18.0",
+    "@testcontainers/postgresql": "^12.2.1"
   },
   "publishConfig": {
     "access": "public"