@kubun/store-credential 0.17.0 → 0.17.2

package/lib/api.d.ts

@@ -299,7 +299,7 @@ export type CredentialStoreAPI = {
     beginProvisioningAttempt(params: {
         ownerDID: string;
         grantorDID: string;
-        attemptId: string;
+        attemptID: string;
     }): Promise<void>;
     /**
      * Record a provisioning attempt's outcome, atomically. If `epoch > heldEpoch`,
@@ -309,7 +309,7 @@ export type CredentialStoreAPI = {
     recordProvisioningAttempt(params: {
         ownerDID: string;
         grantorDID: string;
-        attemptId: string;
+        attemptID: string;
         epoch: number;
         heldEpoch: number;
     }): Promise<{
@@ -325,7 +325,23 @@ export type CredentialStoreAPI = {
     abandonProvisioningAttempt(params: {
         ownerDID: string;
         grantorDID: string;
-        attemptId: string;
+        attemptID: string;
+    }): Promise<void>;
+    /**
+     * Abandon ALL outstanding provisioning attempts for one (owner, grantor)
+     * scope. Deletes every attempt row for the pair, never touches the
+     * expectation floor. The recovery escape hatch when the attempt id is lost.
+     *
+     * Exclusive-recovery contract: this also clears any OTHER live coordinator's
+     * attempt on the same scope (whose later `recordProvisioningAttempt` would
+     * then hit the phantom-attempt guard and not raise the floor). Callers must
+     * ensure no other live attempt exists for the scope before calling. When the
+     * id is known, prefer `abandonProvisioningAttempt`, which is safe under
+     * concurrency.
+     */
+    abandonProvisioningAttempts(params: {
+        ownerDID: string;
+        grantorDID: string;
     }): Promise<void>;
     /**
      * List provisioning expectations for one owner: one row per (owner, grantor)
@@ -345,5 +361,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,9 @@
 import { normalizeDID } from '@kokuin/token';
+/**
+ * `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.
  *
@@ -623,7 +628,7 @@ export function createCredentialStore(db, adapter) {
                 await tx.insertInto('kubun_credential_provisioning_attempts').values({
                     owner_did: ownerDid,
                     grantor_did: grantorDid,
-                    attempt_id: params.attemptId
+                    attempt_id: params.attemptID
                 }).onConflict((oc)=>oc.doNothing()).execute();
             });
         },
@@ -639,12 +644,12 @@ export function createCredentialStore(db, adapter) {
                 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.
-                    const existing = await tx.selectFrom('kubun_credential_provisioning_attempts').select('attempt_id').where('owner_did', '=', ownerDid).where('grantor_did', '=', grantorDid).where('attempt_id', '=', params.attemptId).executeTakeFirst();
+                    const existing = await tx.selectFrom('kubun_credential_provisioning_attempts').select('attempt_id').where('owner_did', '=', ownerDid).where('grantor_did', '=', grantorDid).where('attempt_id', '=', params.attemptID).executeTakeFirst();
                     if (existing == null) {
                         return;
                     }
                     // Delete the attempt row.
-                    await tx.deleteFrom('kubun_credential_provisioning_attempts').where('owner_did', '=', ownerDid).where('grantor_did', '=', grantorDid).where('attempt_id', '=', params.attemptId).execute();
+                    await tx.deleteFrom('kubun_credential_provisioning_attempts').where('owner_did', '=', ownerDid).where('grantor_did', '=', grantorDid).where('attempt_id', '=', params.attemptID).execute();
                     // Raise the floor to max(stored, epoch).
                     await tx.updateTable('kubun_credential_provisioning_expectations').set((eb)=>({
                             epoch_floor: eb.case().when('epoch_floor', '<', params.epoch).then(params.epoch).else(eb.ref('epoch_floor')).end()
@@ -660,7 +665,13 @@ export function createCredentialStore(db, adapter) {
             const ownerDid = normalizeDID(params.ownerDID);
             const grantorDid = normalizeDID(params.grantorDID);
             // Delete ONLY the attempt row, never the floor.
-            await db.deleteFrom('kubun_credential_provisioning_attempts').where('owner_did', '=', ownerDid).where('grantor_did', '=', grantorDid).where('attempt_id', '=', params.attemptId).execute();
+            await db.deleteFrom('kubun_credential_provisioning_attempts').where('owner_did', '=', ownerDid).where('grantor_did', '=', grantorDid).where('attempt_id', '=', params.attemptID).execute();
+        },
+        async abandonProvisioningAttempts (params) {
+            const ownerDid = normalizeDID(params.ownerDID);
+            const grantorDid = normalizeDID(params.grantorDID);
+            // Delete every attempt row for the scope, never the floor.
+            await db.deleteFrom('kubun_credential_provisioning_attempts').where('owner_did', '=', ownerDid).where('grantor_did', '=', grantorDid).execute();
         },
         async listProvisioningExpectations (params) {
             const ownerDid = normalizeDID(params.ownerDID);
@@ -690,6 +701,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

@@ -80,8 +80,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.0",
+  "version": "0.17.2",
   "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": {