@kubun/store-credential 0.17.1 → 0.17.3

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>>;
@@ -228,8 +237,27 @@ export type CredentialStoreAPI = {
     getAliasEntryID(namespace: string, key: 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.
+     */
+    bindAliasIfAbsent(namespace: string, aliasKey: string, entryID: 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
@@ -361,5 +389,48 @@ export type CredentialStoreAPI = {
      * `listProvisioningExpectations` can't give on its own (it's per-owner).
      */
     listProvisioningExpectationOwners(): Promise<Array<string>>;
+    /**
+     * Refresh a controller-owned key's `credential/administer` delegation chain,
+     * gated strictly-greater on `refreshSeq` (stale/replayed is a silent no-op,
+     * same shape as {@link CredentialStoreAPI.putWrappingAuthority}). Handles
+     * both the absent-row insert and the monotone race. Returns whether a row
+     * was inserted or updated.
+     */
+    refreshKeyOwnerDelegation(params: {
+        keyID: string;
+        delegationTokens: Array<string>;
+        refreshSeq: number;
+    }): Promise<boolean>;
+    /**
+     * Compare-and-swap a key-owner delegation chain, guarded on the `revision`
+     * the caller read. Replaces the row only when its CURRENT `revision` still
+     * equals `expectedRevision`, so a writer that read an invalid-present chain
+     * and revalidated it can install a replacement without racing another such
+     * writer or a concurrent refresh. The guard is `revision`, NOT `refreshSeq`:
+     * two distinct valid chains can share a `refreshSeq` (min-exp ms), so guarding
+     * on the seq has an ABA hole. Unlike {@link refreshKeyOwnerDelegation} this
+     * never inserts and is not monotone — it is the escape hatch for the
+     * invalid-present case, where the incoming chain's `refreshSeq` may be lower.
+     * Absent row is a no-op false, same as a revision mismatch. A successful
+     * write bumps `revision`.
+     */
+    replaceKeyOwnerDelegationIfUnchanged(params: {
+        keyID: string;
+        expectedRevision: number;
+        delegationTokens: Array<string>;
+        refreshSeq: number;
+    }): Promise<boolean>;
+    /** The stored delegation chain, its `refreshSeq`, and its `revision`, or `undefined` when unset. */
+    getKeyOwnerDelegation(keyID: string): Promise<{
+        delegationTokens: Array<string>;
+        refreshSeq: number;
+        revision: number;
+    } | undefined>;
 };
+/**
+ * `refreshSeq` sentinel for a delegation chain that has no future refresh —
+ * larger than any real ms timestamp, so a bounded refresh can never overtake
+ * it. Consumed by `@kubun/plugin-p2p`.
+ */
+export declare const UNBOUNDED_REFRESH_SEQ = 8640000000000000;
 export declare function createCredentialStore(db: Kysely<CredentialTables>, adapter: Adapter): CredentialStoreAPI;

package/lib/api.js

@@ -1,4 +1,10 @@
 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
+ * it. Consumed by `@kubun/plugin-p2p`.
+ */ export const UNBOUNDED_REFRESH_SEQ = 8_640_000_000_000_000;
 /**
  * Run `write` as one atomic unit.
  *
@@ -32,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 = {
@@ -87,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);
                 });
             }
@@ -95,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,
@@ -120,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,
@@ -168,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) {
@@ -346,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,
@@ -367,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();
         },
@@ -445,19 +567,134 @@ export function createCredentialStore(db, adapter) {
             return row?.entry_id ?? 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) {
+            // 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).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.
+                    .where((eb)=>eb.exists(eb.selectFrom('kubun_credential_entries as t').select(sql`1`.as('one')).where('t.entry_id', '=', entryID))).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();
@@ -553,7 +790,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();
@@ -612,7 +849,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,
@@ -635,7 +872,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.
@@ -696,6 +933,42 @@ export function createCredentialStore(db, adapter) {
             return [
                 ...owners
             ];
+        },
+        async refreshKeyOwnerDelegation (params) {
+            const values = {
+                key_id: params.keyID,
+                delegation_tokens: adapter.encodeJSON(params.delegationTokens),
+                refresh_seq: params.refreshSeq,
+                revision: 1
+            };
+            const result = await db.insertInto('kubun_credential_key_owner_delegation').values(values).onConflict((oc)=>oc.column('key_id').doUpdateSet({
+                    delegation_tokens: values.delegation_tokens,
+                    refresh_seq: values.refresh_seq,
+                    // Bump so a concurrent replace CAS on the pre-refresh revision fails.
+                    revision: (eb)=>eb('kubun_credential_key_owner_delegation.revision', '+', 1)
+                }).where('kubun_credential_key_owner_delegation.refresh_seq', '<', values.refresh_seq)).executeTakeFirst();
+            return (result.numInsertedOrUpdatedRows ?? 0n) > 0n;
+        },
+        async replaceKeyOwnerDelegationIfUnchanged (params) {
+            const result = await db.updateTable('kubun_credential_key_owner_delegation').set({
+                delegation_tokens: adapter.encodeJSON(params.delegationTokens),
+                refresh_seq: params.refreshSeq,
+                revision: (eb)=>eb('kubun_credential_key_owner_delegation.revision', '+', 1)
+            }).where('key_id', '=', params.keyID).where('revision', '=', params.expectedRevision).executeTakeFirst();
+            return (result.numUpdatedRows ?? 0n) > 0n;
+        },
+        async getKeyOwnerDelegation (keyID) {
+            const row = await db.selectFrom('kubun_credential_key_owner_delegation').select([
+                'delegation_tokens',
+                'refresh_seq',
+                'revision'
+            ]).where('key_id', '=', keyID).executeTakeFirst();
+            if (row == null) return undefined;
+            return {
+                delegationTokens: row.delegation_tokens,
+                refreshSeq: row.refresh_seq,
+                revision: row.revision
+            };
         }
     };
     return api;

package/lib/index.d.ts

@@ -1,8 +1,8 @@
 import type { StoreProvider } from '@kubun/db';
 import type { CredentialStoreAPI } from './api.js';
 export type { CredentialManifestRecord, CredentialOpInput, CredentialStoreAPI, CredentialTombstoneInput, HeldCredentialSubject, ListManifestsParams, NextGrantorSequenceParams, PutCredentialEntryParams, PutCredentialKeyParams, PutCredentialWrappingParams, PutWrappingAuthorityParams, StoredCredentialManifest, WrappingAuthority, } from './api.js';
-export { createCredentialStore } from './api.js';
+export { createCredentialStore, UNBOUNDED_REFRESH_SEQ } from './api.js';
 export { credentialStoreDefinition } from './definition.js';
 export declare const CREDENTIAL_STORE: "credential";
 export declare function getCredentialStore(provider: StoreProvider): Promise<CredentialStoreAPI>;
-export type { CredentialAlias, CredentialEntry, CredentialEntryTable, CredentialEntryWithProvenance, CredentialFactorDescriptor, CredentialGrantorCounter, CredentialGrantorCounterTable, CredentialKey, CredentialKeyBranch, CredentialKeyBranchTable, CredentialKeyState, CredentialKeyTable, CredentialManifest, CredentialManifestKey, CredentialManifestTable, CredentialOp, CredentialOpSubjectKind, CredentialOpTable, CredentialTables, CredentialWrapping, CredentialWrappingAuthority, CredentialWrappingAuthorityTable, CredentialWrappingTable, CredentialWrappingWithBranch, InsertCredentialAlias, InsertCredentialEntry, InsertCredentialGrantorCounter, InsertCredentialKey, InsertCredentialManifest, InsertCredentialOp, InsertCredentialWrapping, InsertCredentialWrappingAuthority, KubunCredentialAliasTable, } from './tables.js';
+export type { CredentialAlias, CredentialEntry, CredentialEntryTable, CredentialEntryWithProvenance, CredentialFactorDescriptor, CredentialGrantorCounter, CredentialGrantorCounterTable, CredentialKey, CredentialKeyBranch, CredentialKeyBranchTable, CredentialKeyOwnerDelegation, CredentialKeyOwnerDelegationTable, CredentialKeyState, CredentialKeyTable, CredentialManifest, CredentialManifestKey, CredentialManifestTable, CredentialOp, CredentialOpSubjectKind, CredentialOpTable, CredentialTables, CredentialWrapping, CredentialWrappingAuthority, CredentialWrappingAuthorityTable, CredentialWrappingTable, CredentialWrappingWithBranch, InsertCredentialAlias, InsertCredentialEntry, InsertCredentialGrantorCounter, InsertCredentialKey, InsertCredentialKeyOwnerDelegation, InsertCredentialManifest, InsertCredentialOp, InsertCredentialWrapping, InsertCredentialWrappingAuthority, KubunCredentialAliasTable, } from './tables.js';

package/lib/index.js

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

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();
@@ -80,8 +82,14 @@ export function getCredentialMigrations(ctx) {
                 'recipient_did',
                 'grantor_did'
             ]).execute();
+            // A controller-owned key's administer delegation chain, keyed on the key
+            // itself; `refresh_seq` gates every upsert strictly-greater.
+            await db.schema.createTable('kubun_credential_key_owner_delegation').ifNotExists().addColumn('key_id', t.text, (col)=>col.notNull().primaryKey()).addColumn('delegation_tokens', t.json, (col)=>col.notNull()).addColumn('refresh_seq', t.bigint, (col)=>col.notNull())// Per-write revision for the replace CAS; `refresh_seq` is not a unique
+            // version (see CredentialKeyOwnerDelegationTable).
+            .addColumn('revision', t.bigint, (col)=>col.notNull()).execute();
         },
         async down (db) {
+            await db.schema.dropTable('kubun_credential_key_owner_delegation').ifExists().execute();
             await db.schema.dropTable('kubun_credential_manifests').ifExists().execute();
             await db.schema.dropTable('kubun_credential_provisioning_attempts').ifExists().execute();
             await db.schema.dropTable('kubun_credential_provisioning_expectations').ifExists().execute();

package/lib/tables.d.ts

@@ -259,6 +259,21 @@ export type CredentialManifestTable = {
 };
 export type CredentialManifest = Selectable<CredentialManifestTable>;
 export type InsertCredentialManifest = Insertable<CredentialManifestTable>;
+/**
+ * A controller-owned key's `credential/administer` delegation chain, keyed on
+ * the key itself rather than a triple — the chain authorizes whoever holds it
+ * to administer THIS key, independent of any one (owner, recipient, grantor)
+ * relationship. `refresh_seq` gates every `refresh` strictly-greater, same
+ * shape as {@link CredentialWrappingAuthorityTable}.
+ */
+export type CredentialKeyOwnerDelegationTable = {
+    key_id: string;
+    delegation_tokens: JSONArrayColumn<string>;
+    refresh_seq: number;
+    revision: number;
+};
+export type CredentialKeyOwnerDelegation = Selectable<CredentialKeyOwnerDelegationTable>;
+export type InsertCredentialKeyOwnerDelegation = Insertable<CredentialKeyOwnerDelegationTable>;
 export type CredentialTables = {
     kubun_credential_keys: CredentialKeyTable;
     kubun_credential_key_branches: CredentialKeyBranchTable;
@@ -272,5 +287,6 @@ export type CredentialTables = {
     kubun_credential_provisioning_expectations: CredentialProvisioningExpectationTable;
     kubun_credential_provisioning_attempts: CredentialProvisioningAttemptTable;
     kubun_credential_manifests: CredentialManifestTable;
+    kubun_credential_key_owner_delegation: CredentialKeyOwnerDelegationTable;
 };
 export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kubun/store-credential",
-  "version": "0.17.1",
+  "version": "0.17.3",
   "keywords": [],
   "license": "see LICENSE.md",
   "sideEffects": false,
@@ -18,11 +18,11 @@
     "@kokuin/token": "^0.5.0",
     "@kubun/db": "^0.17.0",
     "@kubun/db-adapter": "^0.17.0",
-    "kysely": "^0.29.5"
+    "kysely": "^0.29.6"
   },
   "devDependencies": {
     "@kubun/db-better-sqlite": "^0.17.0",
-    "@kubun/db-postgres": "^0.17.0",
+    "@kubun/db-postgres": "^0.17.1",
     "@testcontainers/postgresql": "^12.1.0"
   },
   "publishConfig": {