@kubun/store-credential 0.17.1 → 0.17.2

package/lib/api.d.ts

@@ -361,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.
  *
@@ -696,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.1",
+  "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": {