@kubun/store-credential 0.17.2 → 0.17.4

package/lib/api.d.ts

@@ -1,5 +1,5 @@
 import type { Adapter } from '@kubun/db-adapter';
-import type { Kysely } from 'kysely';
+import { type Kysely } from 'kysely';
 import type { CredentialEntry, CredentialEntryWithProvenance, CredentialFactorDescriptor, CredentialKey, CredentialKeyBranch, CredentialKeyState, CredentialManifestKey, CredentialOp, CredentialOpSubjectKind, CredentialTables, CredentialWrapping, CredentialWrappingWithBranch } from './tables.js';
 /**
  * The persisted half of a credential manifest — a structural subset of the
@@ -183,6 +183,15 @@ export type CredentialStoreAPI = {
      * source and target keys before invoking this capability.
      */
     moveEntry(params: PutCredentialEntryParams, op: CredentialOpInput | null): Promise<void>;
+    /**
+     * Write over an entry's ciphertext ONLY if the row already exists under the
+     * same key — never inserts, never moves it. Op-first like putEntry: the op is
+     * written under the op-conflict lock, then the row; if no matching row is
+     * present (concurrently deleted, or re-keyed away) the op is rolled back, so a
+     * refresh writeback can neither revive a concurrently-deleted entry nor leave
+     * an op stranded without its row. Returns 'absent' when nothing was updated.
+     */
+    updateEntryIfPresent(params: PutCredentialEntryParams, op: CredentialOpInput | null): Promise<'updated' | 'absent'>;
     getEntry(entryID: string): Promise<CredentialEntry | undefined>;
     getEntryWithProvenance(entryID: string): Promise<CredentialEntryWithProvenance | undefined>;
     listEntries(keyID: string): Promise<Array<CredentialEntry>>;
@@ -226,10 +235,48 @@ export type CredentialStoreAPI = {
      * whatever it means by "key" before calling.
      */
     getAliasEntryID(namespace: string, key: string): Promise<string | null>;
+    /**
+     * The provider namespace this entry is aliased under, or null when the entry
+     * has no alias row. UNIQUE(entry_id) makes this a 1:1 reverse lookup.
+     */
+    aliasNamespaceForEntry(entryID: string): Promise<string | null>;
     /** Point `(namespace, key)` at `entryID`, replacing any prior target. */
     setAliasEntryID(namespace: string, key: string, entryID: string): Promise<void>;
+    /**
+     * Bind `(namespace, aliasKey)` to `entryID` only if the alias slot is free and
+     * the entry exists — unlike {@link setAliasEntryID}, this never overwrites an
+     * existing alias and never binds a nonexistent entry. Classifies the outcome
+     * instead of throwing, since both unique constraints are expected outcomes a
+     * caller branches on, not exceptional ones.
+     *
+     * When `expectedKeyID` is given, the bind is additionally conditioned, in the
+     * same statement, on the entry belonging to that key. This closes a
+     * time-of-check/time-of-use gap for callers that cannot wrap the check and the
+     * bind in one transaction: an entry verified to belong to a key can be moved to
+     * another key (a supported manager operation) before an unconditioned insert
+     * fires, which would point this alias at an entry now owned by a different key.
+     * Folding the key check into the insert refuses atomically. When omitted, only
+     * entry existence is required (owner-gated callers verify authority elsewhere).
+     */
+    bindAliasIfAbsent(params: {
+        namespace: string;
+        aliasKey: string;
+        entryID: string;
+        expectedKeyID?: string;
+    }): Promise<'inserted' | 'entry-missing' | {
+        conflict: 'alias';
+        existing: string;
+    } | {
+        conflict: 'entry';
+    }>;
     /** Clear an alias. A no-op, not an error, when none is set. */
     deleteAliasEntryID(namespace: string, key: string): Promise<void>;
+    /**
+     * Clear an alias only while it still points at `entryID`. A concurrent rebind
+     * that repaired the pointer onto a fresh entry in the gap after the old entry
+     * was deleted is left intact; a no-op when the pointer already moved or is unset.
+     */
+    deleteAliasIfEntry(namespace: string, key: string, entryID: string): Promise<void>;
     /**
      * The distinct keys currently set within `namespace`. Keys stay opaque here —
      * a caller interprets them (e.g. connector credentials store the normalized

package/lib/api.js

@@ -1,4 +1,5 @@
 import { normalizeDID } from '@kokuin/token';
+import { sql } from 'kysely';
 /**
  * `refreshSeq` sentinel for a delegation chain that has no future refresh —
  * larger than any real ms timestamp, so a bounded refresh can never overtake
@@ -37,6 +38,26 @@ import { normalizeDID } from '@kokuin/token';
         }).where('kubun_credential_wrapping_authority.refresh_seq', '<', values.refresh_seq)).execute();
 }
 const OP_REJECTED = Symbol('credential op rejected');
+// A repair that repoints a dangling alias can collide with UNIQUE(entry_id) when the
+// caller's entry is already aliased under another name. The error classes and codes
+// share nothing across the two drivers, so match a uniqueness marker AND the exact
+// identifier each driver reports — never a bare substring, which would also swallow an
+// unrelated error that merely mentions the column. Postgres: SQLSTATE 23505 plus the
+// constraint name (on the error or in the message). SQLite: "UNIQUE constraint failed"
+// plus the table.column.
+function isEntryAliasUniqueViolation(error) {
+    if (error == null || typeof error !== 'object') return false;
+    const { message, code, constraint_name, constraint } = error;
+    const msg = typeof message === 'string' ? message : '';
+    const name = typeof constraint === 'string' && constraint || typeof constraint_name === 'string' && constraint_name || '';
+    const entryConstraint = 'uq_kubun_credential_aliases_entry' // Postgres constraint
+    ;
+    const entryColumn = 'kubun_credential_aliases.entry_id' // SQLite column
+    ;
+    const postgres = (code === '23505' || msg.includes('duplicate key value')) && (name === entryConstraint || msg.includes(entryConstraint));
+    const sqlite = msg.includes('UNIQUE constraint failed') && msg.includes(entryColumn);
+    return postgres || sqlite;
+}
 async function writeOp(params) {
     const { db, subjectKind, subjectID, op, deleted, allowKeyMove = false } = params;
     const values = {
@@ -92,7 +113,7 @@ export function createCredentialStore(db, adapter) {
             if (accept == null) {
                 await write(db);
             } else {
-                await writeAtomically(db, async (tx)=>{
+                await writeAmbient(db, async (tx)=>{
                     if (await accept(tx)) await write(tx);
                 });
             }
@@ -100,7 +121,7 @@ export function createCredentialStore(db, adapter) {
         }
         const ownsTransaction = !db.isTransaction;
         try {
-            await writeAtomically(db, async (tx)=>{
+            await writeAmbient(db, async (tx)=>{
                 if (!await writeOp({
                     db: tx,
                     subjectKind,
@@ -125,7 +146,7 @@ export function createCredentialStore(db, adapter) {
             await remove(db);
             return;
         }
-        await writeAtomically(db, async (tx)=>{
+        await writeAmbient(db, async (tx)=>{
             if (!await writeOp({
                 db: tx,
                 subjectKind,
@@ -173,6 +194,32 @@ export function createCredentialStore(db, adapter) {
             allowKeyMove: allowMove
         });
     }
+    // One async gate serializes EVERY write that joins a caller-supplied ambient
+    // transaction. The SAVEPOINT sections below (updateEntryIfPresent's op+row fence,
+    // bindAliasIfAbsent's repair fence) then hold the connection exclusively for their
+    // 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);
     const api = {
         async transaction (fn) {
             if (db.isTransaction) {
@@ -351,7 +398,7 @@ export function createCredentialStore(db, adapter) {
                 await remove(db);
                 return;
             }
-            await writeAtomically(db, async (tx)=>{
+            await writeAmbient(db, async (tx)=>{
                 for (const tombstone of tombstones){
                     if (!await writeOp({
                         db: tx,
@@ -372,6 +419,76 @@ export function createCredentialStore(db, adapter) {
         async moveEntry (params, op) {
             await writeEntry(params, op, true);
         },
+        async updateEntryIfPresent (params, op) {
+            let outcome = 'absent';
+            const runWrite = async (tx)=>{
+                // Op-first, like putEntry/deleteEntry: take the op lock before the entry row,
+                // the same order deleteEntry uses, so a row-first inversion cannot deadlock a
+                // concurrent delete. writeOp's LWW guard rejects a stale-HLC writeback and its
+                // key_id predicate (default allowKeyMove = false) one aimed at a key the entry
+                // was re-keyed away from; either way it returns false and nothing is touched.
+                // Its insert branch mints the signed op for a GraphQL-created op-less entry
+                // (putEntry(..., null)), so that entry's first refresh is preserved.
+                if (op != null && !await writeOp({
+                    db: tx,
+                    subjectKind: 'entry',
+                    subjectID: params.entryID,
+                    op,
+                    deleted: 0
+                })) {
+                    return;
+                }
+                // The op winning does NOT prove the entry row is present under this key: the
+                // GraphQL admin surface writes a row with no op (putEntry(..., null)) and
+                // removes a row without touching its op (deleteEntry(..., null)), so the row
+                // can be absent or re-keyed here. UPDATE-only, keyed on entry_id AND key_id;
+                // on a miss, throw to roll the provisional op back, so op and row never
+                // diverge and no live op is left without its row.
+                const result = await tx.updateTable('kubun_credential_entries').set({
+                    key_version: params.keyVersion,
+                    iv: adapter.encodeBinary(params.iv),
+                    ciphertext: adapter.encodeBinary(params.ciphertext),
+                    hlc: params.hlc
+                }).where('entry_id', '=', params.entryID).where('key_id', '=', params.keyID).executeTakeFirst();
+                if ((result.numUpdatedRows ?? 0n) === 0n) {
+                    if (op != null) throw OP_REJECTED;
+                    return;
+                }
+                outcome = 'updated';
+            };
+            if (!db.isTransaction) {
+                // We own the transaction: writeAtomically opens it and an OP_REJECTED throw
+                // rolls the provisional op back before it can commit.
+                try {
+                    await writeAmbient(db, runWrite);
+                } catch (error) {
+                    if (error === OP_REJECTED) return 'absent';
+                    throw error;
+                }
+                return outcome;
+            }
+            // Ambient caller transaction (e.g. a connector mutation's per-request refresh
+            // stack joins its tx). writeAtomically runs inline here with no rollback fence,
+            // and the refresh decorator catches every writeback error — so a bare throw
+            // would leave the provisional op committed with no row. Fence the op+row writes
+            // in a savepoint: a miss rolls back ONLY the provisional op, leaving the
+            // caller's transaction intact. The section runs under withAmbientWrite so no other
+            // ambient write can land inside this savepoint window and be reverted with it.
+            // SAVEPOINT is portable across SQLite and Postgres.
+            return await withAmbientWrite(async ()=>{
+                await sql`SAVEPOINT kubun_cred_update_entry`.execute(db);
+                try {
+                    await runWrite(db);
+                } catch (error) {
+                    await sql`ROLLBACK TO SAVEPOINT kubun_cred_update_entry`.execute(db);
+                    await sql`RELEASE SAVEPOINT kubun_cred_update_entry`.execute(db);
+                    if (error === OP_REJECTED) return 'absent';
+                    throw error;
+                }
+                await sql`RELEASE SAVEPOINT kubun_cred_update_entry`.execute(db);
+                return outcome;
+            });
+        },
         async getEntry (entryID) {
             return await db.selectFrom('kubun_credential_entries').selectAll().where('entry_id', '=', entryID).executeTakeFirst();
         },
@@ -449,20 +566,144 @@ export function createCredentialStore(db, adapter) {
             const row = await db.selectFrom('kubun_credential_aliases').select('entry_id').where('namespace', '=', namespace).where('alias_key', '=', key).executeTakeFirst();
             return row?.entry_id ?? null;
         },
+        async aliasNamespaceForEntry (entryID) {
+            const row = await db.selectFrom('kubun_credential_aliases').select('namespace').where('entry_id', '=', entryID).executeTakeFirst();
+            return row?.namespace ?? null;
+        },
         async setAliasEntryID (namespace, key, entryID) {
-            await db.insertInto('kubun_credential_aliases').values({
-                namespace,
-                alias_key: key,
-                entry_id: entryID
-            }).onConflict((oc)=>oc.columns([
-                    'namespace',
-                    'alias_key'
-                ]).doUpdateSet({
+            await gatedIfAmbient(()=>db.insertInto('kubun_credential_aliases').values({
+                    namespace,
+                    alias_key: key,
                     entry_id: entryID
-                })).execute();
+                }).onConflict((oc)=>oc.columns([
+                        'namespace',
+                        'alias_key'
+                    ]).doUpdateSet({
+                        entry_id: entryID
+                    })).execute());
+        },
+        async bindAliasIfAbsent ({ namespace, aliasKey, entryID, expectedKeyID }) {
+            // Entry-existence-conditioned insert: the alias row is written only in the same
+            // statement that confirms the entry exists. ON CONFLICT DO NOTHING fires for either
+            // the (namespace, alias_key) PK or the UNIQUE(entry_id); the read-back names which.
+            //
+            // The table has no FK to entries (SQLite ships with foreign_keys OFF, so a declared
+            // FK would be unenforced there). The INSERT...SELECT closes the race on any
+            // single-writer store; deleteCredential removes the entry before the pointer so a
+            // bind racing a delete refuses cleanly rather than dangling. A pointer that still
+            // outlives its entry (a Postgres delete committing mid-statement) is recovered two
+            // ways: getCredential/getCredentialRef resolve a missing entry to null, and the
+            // repair path below repoints a dangling pointer to a fresh, present entry.
+            const tryInsert = async ()=>{
+                const inserted = await gatedIfAmbient(()=>db.insertInto('kubun_credential_aliases').columns([
+                        'namespace',
+                        'alias_key',
+                        'entry_id'
+                    ]).expression((eb)=>eb.selectFrom('kubun_credential_entries').where('entry_id', '=', entryID)// Same-statement key gate (see doc): bind only while the entry
+                        // still belongs to expectedKeyID, so a concurrent cross-key move
+                        // cannot slip an alias onto an entry that has left this key.
+                        .$if(expectedKeyID != null, (qb)=>qb.where('key_id', '=', expectedKeyID)).select((eb2)=>[
+                                eb2.val(namespace).as('namespace'),
+                                eb2.val(aliasKey).as('alias_key'),
+                                eb2.ref('entry_id').as('entry_id')
+                            ])).onConflict((oc)=>oc.doNothing()).returning('entry_id').executeTakeFirst());
+                return inserted != null;
+            };
+            const aliasAt = async ()=>{
+                const row = await db.selectFrom('kubun_credential_aliases').select('entry_id').where('namespace', '=', namespace).where('alias_key', '=', aliasKey).executeTakeFirst();
+                return row?.entry_id ?? null;
+            };
+            const entryExists = async (id)=>{
+                const row = await db.selectFrom('kubun_credential_entries').select('entry_id').where('entry_id', '=', id).executeTakeFirst();
+                return row != null;
+            };
+            // Repoint this alias to entryID, but ONLY while its stored pointer is still
+            // dangling (its entry row absent), so a concurrently-installed valid binding is
+            // never overwritten — the no-repoint guarantee. A UNIQUE(entry_id) clash (entryID
+            // already aliased elsewhere) must not abort an ambient Postgres transaction, so a
+            // caller-tx write is fenced in a savepoint and the clash mapped to conflict:'entry'.
+            const repairDangling = async (observedExisting)=>{
+                const doUpdate = async ()=>{
+                    const res = await db.updateTable('kubun_credential_aliases').set({
+                        entry_id: entryID
+                    }).where('namespace', '=', namespace).where('alias_key', '=', aliasKey)// Compare-and-swap on the pointer: repoint only while it still holds the
+                    // dangling id we observed. If a concurrent transaction repointed it onto a
+                    // freshly created entry, this matches zero rows — under Postgres READ
+                    // COMMITTED the re-checked current row carries the new id, so a valid binding
+                    // is never overwritten even when that new entry is outside our snapshot.
+                    .where('entry_id', '=', observedExisting)// The observed pointer must still be dangling (its entry absent)...
+                    .where((eb)=>eb.not(eb.exists(eb.selectFrom('kubun_credential_entries as e').select(sql`1`.as('one')).whereRef('e.entry_id', '=', 'kubun_credential_aliases.entry_id'))))// ...and the target must be present, so repair can never form a NEW dangling
+                    // pointer even if the target is deleted between the pre-check and here.
+                    // When key-gated, the target must also still belong to expectedKeyID, so a
+                    // repair cannot repoint onto an entry that has moved to another key.
+                    .where((eb)=>eb.exists(eb.selectFrom('kubun_credential_entries as t').select(sql`1`.as('one')).where('t.entry_id', '=', entryID).$if(expectedKeyID != null, (qb)=>qb.where('t.key_id', '=', expectedKeyID)))).executeTakeFirst();
+                    return (res.numUpdatedRows ?? 0n) > 0n;
+                };
+                if (!db.isTransaction) {
+                    try {
+                        return await doUpdate();
+                    } catch (error) {
+                        if (isEntryAliasUniqueViolation(error)) return 'entry-clash';
+                        throw error;
+                    }
+                }
+                return await withAmbientWrite(async ()=>{
+                    await sql`SAVEPOINT kubun_cred_bind_repair`.execute(db);
+                    try {
+                        const repaired = await doUpdate();
+                        await sql`RELEASE SAVEPOINT kubun_cred_bind_repair`.execute(db);
+                        return repaired;
+                    } catch (error) {
+                        await sql`ROLLBACK TO SAVEPOINT kubun_cred_bind_repair`.execute(db);
+                        await sql`RELEASE SAVEPOINT kubun_cred_bind_repair`.execute(db);
+                        if (isEntryAliasUniqueViolation(error)) return 'entry-clash';
+                        throw error;
+                    }
+                });
+            };
+            if (await tryInsert()) return 'inserted';
+            if (!await entryExists(entryID)) return 'entry-missing';
+            const existing = await aliasAt();
+            // PK free but the insert did not fire and the entry exists → the caller's entry is
+            // already aliased under another name (UNIQUE(entry_id)).
+            if (existing == null) return {
+                conflict: 'entry'
+            };
+            if (existing === entryID) return {
+                conflict: 'alias',
+                existing
+            };
+            // PK held by a different entry; repair only if that pointer is dangling.
+            if (await entryExists(existing)) return {
+                conflict: 'alias',
+                existing
+            };
+            const repaired = await repairDangling(existing);
+            if (repaired === true) return 'inserted';
+            if (repaired === 'entry-clash') return {
+                conflict: 'entry'
+            };
+            // The pointer stopped being dangling under us, or the target vanished (a
+            // concurrent rebind, repair, or delete). Reclassify against the current state,
+            // re-checking the target so a target that disappeared reports entry-missing
+            // rather than a spurious entry conflict.
+            if (await tryInsert()) return 'inserted';
+            if (!await entryExists(entryID)) return 'entry-missing';
+            const now = await aliasAt();
+            if (now == null) return {
+                conflict: 'entry'
+            };
+            if (now === entryID) return 'inserted';
+            return {
+                conflict: 'alias',
+                existing: now
+            };
         },
         async deleteAliasEntryID (namespace, key) {
-            await db.deleteFrom('kubun_credential_aliases').where('namespace', '=', namespace).where('alias_key', '=', key).execute();
+            await gatedIfAmbient(()=>db.deleteFrom('kubun_credential_aliases').where('namespace', '=', namespace).where('alias_key', '=', key).execute());
+        },
+        async deleteAliasIfEntry (namespace, key, entryID) {
+            await gatedIfAmbient(()=>db.deleteFrom('kubun_credential_aliases').where('namespace', '=', namespace).where('alias_key', '=', key).where('entry_id', '=', entryID).execute());
         },
         async listAliasKeys (namespace) {
             const rows = await db.selectFrom('kubun_credential_aliases').select('alias_key').distinct().where('namespace', '=', namespace).execute();
@@ -558,7 +799,7 @@ export function createCredentialStore(db, adapter) {
             const owner = normalizeDID(params.ownerDID);
             const recipient = normalizeDID(params.recipientDID);
             const grantor = normalizeDID(params.grantorDID);
-            await writeAtomically(db, async (tx)=>{
+            await writeAmbient(db, async (tx)=>{
                 await tx.updateTable('kubun_credential_manifests').set((eb)=>({
                         epoch: eb.ref('kubun_credential_manifests.epoch')
                     })).where('owner_did', '=', owner).where('recipient_did', '=', recipient).where('grantor_did', '=', grantor).execute();
@@ -617,7 +858,7 @@ export function createCredentialStore(db, adapter) {
         async beginProvisioningAttempt (params) {
             const ownerDid = normalizeDID(params.ownerDID);
             const grantorDid = normalizeDID(params.grantorDID);
-            await writeAtomically(db, async (tx)=>{
+            await writeAmbient(db, async (tx)=>{
                 // Ensure the expectation floor row exists, idempotent at floor 0.
                 await tx.insertInto('kubun_credential_provisioning_expectations').values({
                     owner_did: ownerDid,
@@ -640,7 +881,7 @@ export function createCredentialStore(db, adapter) {
                 status: 'retry',
                 minEpoch: params.heldEpoch
             };
-            await writeAtomically(db, async (tx)=>{
+            await writeAmbient(db, async (tx)=>{
                 if (params.epoch > params.heldEpoch) {
                     // Phantom-attempt guard: if the id names no live attempt, move
                     // nothing — raising the floor for it would wedge readiness forever.

package/lib/migrations.js

@@ -48,6 +48,8 @@ export function getCredentialMigrations(ctx) {
             await db.schema.createTable('kubun_credential_aliases').ifNotExists().addColumn('namespace', t.text, (col)=>col.notNull()).addColumn('alias_key', t.text, (col)=>col.notNull()).addColumn('entry_id', t.text, (col)=>col.notNull()).addColumn('created_at', t.timestamp, (col)=>col.defaultTo(now).notNull()).addPrimaryKeyConstraint('pk_kubun_credential_aliases', [
                 'namespace',
                 'alias_key'
+            ]).addUniqueConstraint('uq_kubun_credential_aliases_entry', [
+                'entry_id'
             ]).execute();
             // Grantor-authority envelope for a wrapping; `refresh_seq` gates every upsert strictly-greater.
             await db.schema.createTable('kubun_credential_wrapping_authority').ifNotExists().addColumn('wrapping_id', t.text, (col)=>col.notNull().primaryKey()).addColumn('authority_token', t.text, (col)=>col.notNull()).addColumn('refresh_seq', 'integer', (col)=>col.notNull()).execute();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kubun/store-credential",
-  "version": "0.17.2",
+  "version": "0.17.4",
   "keywords": [],
   "license": "see LICENSE.md",
   "sideEffects": false,