@kubun/store-credential 0.14.0 → 0.15.0

package/lib/api.d.ts

@@ -1,6 +1,54 @@
 import type { Adapter } from '@kubun/db-adapter';
 import type { Kysely } from 'kysely';
-import type { CredentialEntry, CredentialEntryWithProvenance, CredentialFactorDescriptor, CredentialKey, CredentialKeyBranch, CredentialKeyState, CredentialOp, CredentialOpSubjectKind, CredentialTables, CredentialWrapping, CredentialWrappingWithBranch } from './tables.js';
+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
+ * plugin's signed `CredentialManifestClaim`, so a verified claim can pass
+ * straight to {@link CredentialStoreAPI.putManifest} without mapping. This
+ * package neither signs nor verifies; the raw token rides alongside as `token`.
+ */
+export type CredentialManifestRecord = {
+    ownerDID: string;
+    recipientDID: string;
+    grantorDID: string;
+    epoch: number;
+    sequence: number;
+    keys: Array<CredentialManifestKey>;
+};
+export type ListManifestsParams = {
+    ownerDID: string;
+    recipientDID: string;
+};
+/** One stored manifest: its persisted record, the signed token that authored it, and delegation tokens. */
+export type StoredCredentialManifest = {
+    record: CredentialManifestRecord;
+    token: string;
+    delegationTokens: Array<string>;
+};
+export type PutWrappingAuthorityParams = {
+    wrappingID: string;
+    envelope: string;
+    refreshSeq: number;
+};
+export type WrappingAuthority = {
+    envelope: string;
+    refreshSeq: number;
+};
+export type NextGrantorSequenceParams = {
+    ownerDID: string;
+    recipientDID: string;
+    grantorDID: string;
+};
+export type NextProvisioningEpochParams = {
+    ownerDID: string;
+    recipientDID: string;
+    grantorDID: string;
+    minEpoch: number;
+};
+export type ListDistributableKeysParams = {
+    ownerDID: string;
+    grantorDID: string;
+};
 /**
  * The signed op that produced a row's current state, as the store holds it.
  *
@@ -77,6 +125,13 @@ export type HeldCredentialSubject = {
  * query context passes it today: it holds a viewer's DID and no signing key.
  */
 export type CredentialStoreAPI = {
+    /**
+     * Run `fn` against a `CredentialStoreAPI` scoped to one atomic transaction.
+     * Nesting-safe: if `this` is already bound to an open Kysely transaction,
+     * `fn` runs inline against `this` instead of opening a second one (Kysely
+     * has no nested transactions), so callers can invoke this unconditionally.
+     */
+    transaction<R>(fn: (store: CredentialStoreAPI) => Promise<R>): Promise<R>;
     putKey(params: PutCredentialKeyParams, op: CredentialOpInput | null): Promise<void>;
     getKey(keyID: string): Promise<CredentialKey | undefined>;
     listKeys(ownerDID: string): Promise<Array<CredentialKey>>;
@@ -94,7 +149,17 @@ export type CredentialStoreAPI = {
         branchID: string;
     }): Promise<void>;
     listKeyBranches(keyID: string, keyVersion: number): Promise<Array<CredentialKeyBranch>>;
-    putWrapping(params: PutCredentialWrappingParams, op: CredentialOpInput | null): Promise<void>;
+    /**
+     * `authority`, when present, upserts the wrapping's grantor-authority envelope
+     * in the SAME transaction as the wrapping row and its op, so a crash can't
+     * leave a held wrapping this device can't later prove was authorized. Omitted
+     * for an owner-signed wrapping. Gated strictly-greater on `refreshSeq`, same
+     * as {@link CredentialStoreAPI.putWrappingAuthority}.
+     */
+    putWrapping(params: PutCredentialWrappingParams, op: CredentialOpInput | null, authority?: {
+        envelope: string;
+        refreshSeq: number;
+    }): Promise<void>;
     getWrapping(wrappingID: string): Promise<CredentialWrapping | undefined>;
     /** Every wrapping for a key, or only those at one version. */
     listWrappings(keyID: string, keyVersion?: number): Promise<Array<CredentialWrapping>>;
@@ -165,5 +230,120 @@ export type CredentialStoreAPI = {
     setAliasEntryID(namespace: string, key: string, entryID: string): Promise<void>;
     /** Clear an alias. A no-op, not an error, when none is set. */
     deleteAliasEntryID(namespace: string, key: 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
+     * owner DID as the key under a provider namespace). Empty for an unused
+     * namespace.
+     */
+    listAliasKeys(namespace: string): Promise<Array<string>>;
+    /** Store a wrapping's grantor-authority envelope; gated strictly-greater on `refreshSeq` (stale/replayed is a silent no-op). */
+    putWrappingAuthority(params: PutWrappingAuthorityParams): Promise<void>;
+    /** The stored envelope and its `refreshSeq`, or `undefined` when unset. */
+    getWrappingAuthority(wrappingID: string): Promise<WrappingAuthority | undefined>;
+    /**
+     * Mint the next `refreshSeq` for one `(ownerDID, recipientDID, grantorDID)`
+     * triple: 1 on the first call, strictly increasing thereafter. Persisted, so
+     * a restart never reissues a number already handed out.
+     */
+    nextGrantorSequence(params: NextGrantorSequenceParams): Promise<number>;
+    /**
+     * Allocate the next `epoch` for one `(ownerDID, recipientDID, grantorDID)`
+     * triple: returns `max(stored, minEpoch) + 1` on each call, so the value is
+     * strictly increasing but a floor can jump it forward. Persisted; never
+     * reissues an epoch already handed out. Triple is keyed on normalized DIDs,
+     * so a `did:peer:4` short/long form converge on one row.
+     */
+    nextProvisioningEpoch(params: NextProvisioningEpochParams): Promise<number>;
+    /**
+     * Store a grantor's manifest, gated lexicographically on `(epoch, sequence)`
+     * per `(ownerDID, recipientDID, grantorDID)` triple — higher epoch always
+     * wins, sequence breaks ties within an epoch; a stale/replayed value is a
+     * silent no-op. Triple keyed on normalized DIDs. `token` is the raw signed
+     * manifest; `delegationTokens` are optional wrappings that authorized it.
+     */
+    putManifest(record: CredentialManifestRecord, token: string, delegationTokens?: Array<string>): Promise<void>;
+    /**
+     * Every grantor's manifest for one `(ownerDID, recipientDID)`, one row per
+     * grantor. Arguments are normalized before query, matching
+     * {@link CredentialStoreAPI.putManifest}'s normalize-on-write.
+     */
+    listManifests(params: ListManifestsParams): Promise<Array<StoredCredentialManifest>>;
+    /**
+     * Take the write lock on the manifest row so a held-epoch read later in the
+     * SAME transaction can't race a concurrent {@link CredentialStoreAPI.putManifest}.
+     * A value-preserving UPDATE, not `FOR UPDATE` (SQLite rejects that syntax) —
+     * it blocks a concurrent Postgres writer the same way; SQLite is already
+     * single-writer-serialized. No-op if the row doesn't exist yet; that
+     * first-write race is benign (held epoch 0).
+     */
+    lockManifestRow(params: {
+        ownerDID: string;
+        recipientDID: string;
+        grantorDID: string;
+    }): Promise<void>;
+    /**
+     * Every active owner key for which a wrapping exists at the key's current
+     * version addressed (after normalization) to the grantor. One snapshot read;
+     * in-memory DID normalization. Deduped by keyID.
+     */
+    listDistributableKeys(params: ListDistributableKeysParams): Promise<Array<{
+        keyID: string;
+        version: number;
+    }>>;
+    /**
+     * Begin tracking a provisioning attempt, idempotent on the id. Ensures an
+     * expectation floor row exists (at 0) if none yet. The attempt counts toward
+     * outstanding and blocks readiness until cleared.
+     */
+    beginProvisioningAttempt(params: {
+        ownerDID: string;
+        grantorDID: string;
+        attemptId: string;
+    }): Promise<void>;
+    /**
+     * Record a provisioning attempt's outcome, atomically. If `epoch > heldEpoch`,
+     * clears the attempt row and raises the expectation floor to
+     * `max(stored, epoch)`; otherwise leaves the attempt row and returns retry.
+     */
+    recordProvisioningAttempt(params: {
+        ownerDID: string;
+        grantorDID: string;
+        attemptId: string;
+        epoch: number;
+        heldEpoch: number;
+    }): Promise<{
+        status: 'recorded';
+    } | {
+        status: 'retry';
+        minEpoch: number;
+    }>;
+    /**
+     * Abandon a provisioning attempt. Deletes ONLY the attempt row, never touches
+     * the expectation floor.
+     */
+    abandonProvisioningAttempt(params: {
+        ownerDID: string;
+        grantorDID: string;
+        attemptId: string;
+    }): Promise<void>;
+    /**
+     * List provisioning expectations for one owner: one row per (owner, grantor)
+     * pair currently held. Returns the expectation floor and count of outstanding
+     * attempts. Normalizes ownerDID on read.
+     */
+    listProvisioningExpectations(params: {
+        ownerDID: string;
+    }): Promise<Array<{
+        grantorDID: string;
+        epochFloor: number;
+        outstanding: number;
+    }>>;
+    /**
+     * Every distinct owner DID with a provisioning expectation row, normalized
+     * and de-duped — the catalog-independent enumeration
+     * `listProvisioningExpectations` can't give on its own (it's per-owner).
+     */
+    listProvisioningExpectationOwners(): Promise<Array<string>>;
 };
 export declare function createCredentialStore(db: Kysely<CredentialTables>, adapter: Adapter): CredentialStoreAPI;

package/lib/api.js

@@ -16,6 +16,21 @@ import { normalizeDID } from '@kokuin/token';
         await write(tx);
     });
 }
+/**
+ * The strictly-greater-`refreshSeq` upsert shared by {@link CredentialStoreAPI.putWrappingAuthority}
+ * and `putWrapping`'s own-transaction variant — one predicate, so the two entry
+ * points cannot drift on what "newer" means.
+ */ async function upsertWrappingAuthority(db, params) {
+    const values = {
+        wrapping_id: params.wrappingID,
+        authority_token: params.envelope,
+        refresh_seq: params.refreshSeq
+    };
+    await db.insertInto('kubun_credential_wrapping_authority').values(values).onConflict((oc)=>oc.column('wrapping_id').doUpdateSet({
+            authority_token: values.authority_token,
+            refresh_seq: values.refresh_seq
+        }).where('kubun_credential_wrapping_authority.refresh_seq', '<', values.refresh_seq)).execute();
+}
 const OP_REJECTED = Symbol('credential op rejected');
 async function writeOp(params) {
     const { db, subjectKind, subjectID, op, deleted, allowKeyMove = false } = params;
@@ -153,7 +168,13 @@ export function createCredentialStore(db, adapter) {
             allowKeyMove: allowMove
         });
     }
-    return {
+    const api = {
+        async transaction (fn) {
+            if (db.isTransaction) {
+                return await fn(api);
+            }
+            return await db.transaction().execute(async (tx)=>await fn(createCredentialStore(tx, adapter)));
+        },
         async putKey (params, op) {
             await writeSubject({
                 subjectKind: 'key',
@@ -241,7 +262,7 @@ export function createCredentialStore(db, adapter) {
         async listKeyBranches (keyID, keyVersion) {
             return await db.selectFrom('kubun_credential_key_branches').selectAll().where('key_id', '=', keyID).where('key_version', '=', keyVersion).orderBy('branch_id', 'asc').execute();
         },
-        async putWrapping (params, op) {
+        async putWrapping (params, op, authority) {
             const values = {
                 wrapping_id: params.wrappingID,
                 key_id: params.keyID,
@@ -271,6 +292,15 @@ export function createCredentialStore(db, adapter) {
                     if ((result.numInsertedOrUpdatedRows ?? 0n) === 0n) {
                         throw new Error(`Credential wrapping ${params.wrappingID} belongs to another key`);
                     }
+                    // Runs only after `writeOp` wins its LWW race, so a superseded
+                    // wrapping never persists an envelope it didn't actually establish.
+                    if (authority != null) {
+                        await upsertWrappingAuthority(tx, {
+                            wrappingID: params.wrappingID,
+                            envelope: authority.envelope,
+                            refreshSeq: authority.refreshSeq
+                        });
+                    }
                 }
             });
         },
@@ -428,8 +458,241 @@ export function createCredentialStore(db, adapter) {
         },
         async deleteAliasEntryID (namespace, key) {
             await db.deleteFrom('kubun_credential_aliases').where('namespace', '=', namespace).where('alias_key', '=', key).execute();
+        },
+        async listAliasKeys (namespace) {
+            const rows = await db.selectFrom('kubun_credential_aliases').select('alias_key').distinct().where('namespace', '=', namespace).execute();
+            return rows.map((row)=>row.alias_key);
+        },
+        async putWrappingAuthority (params) {
+            await upsertWrappingAuthority(db, params);
+        },
+        async getWrappingAuthority (wrappingID) {
+            const row = await db.selectFrom('kubun_credential_wrapping_authority').select([
+                'authority_token',
+                'refresh_seq'
+            ]).where('wrapping_id', '=', wrappingID).executeTakeFirst();
+            if (row == null) return undefined;
+            return {
+                envelope: row.authority_token,
+                refreshSeq: row.refresh_seq
+            };
+        },
+        async nextGrantorSequence (params) {
+            // Atomic INSERT ... ON CONFLICT DO UPDATE increments in place, so two
+            // concurrent callers can't observe the same seq. Normalize the tuple
+            // HERE (not left to callers) so a did:peer:4 recipient's short/long
+            // forms converge on one counter instead of splitting into two.
+            const row = await db.insertInto('kubun_credential_grantor_counters').values({
+                owner_did: normalizeDID(params.ownerDID),
+                recipient_did: normalizeDID(params.recipientDID),
+                grantor_did: normalizeDID(params.grantorDID),
+                seq: 1
+            }).onConflict((oc)=>oc.columns([
+                    'owner_did',
+                    'recipient_did',
+                    'grantor_did'
+                ]).doUpdateSet((eb)=>({
+                        seq: eb('kubun_credential_grantor_counters.seq', '+', 1)
+                    }))).returning('seq').executeTakeFirstOrThrow();
+            return row.seq;
+        },
+        async nextProvisioningEpoch (params) {
+            // Atomic upsert to max(stored, minEpoch) + 1, guaranteeing monotonicity.
+            // Normalize the tuple HERE, same reasoning as `nextGrantorSequence`.
+            const ownerDid = normalizeDID(params.ownerDID);
+            const recipientDid = normalizeDID(params.recipientDID);
+            const grantorDid = normalizeDID(params.grantorDID);
+            const floor = Math.max(0, params.minEpoch);
+            const row = await db.insertInto('kubun_credential_provisioning_epochs').values({
+                owner_did: ownerDid,
+                recipient_did: recipientDid,
+                grantor_did: grantorDid,
+                epoch: floor + 1
+            }).onConflict((oc)=>oc.columns([
+                    'owner_did',
+                    'recipient_did',
+                    'grantor_did'
+                ]).doUpdateSet((eb)=>({
+                        // max(stored, floor) + 1, expressed without a portable GREATEST:
+                        epoch: eb.case().when('kubun_credential_provisioning_epochs.epoch', '<', floor).then(floor + 1).else(eb('kubun_credential_provisioning_epochs.epoch', '+', 1)).end()
+                    }))).returning('epoch').executeTakeFirstOrThrow();
+            return row.epoch;
+        },
+        async putManifest (record, token, delegationTokens) {
+            const values = {
+                owner_did: normalizeDID(record.ownerDID),
+                recipient_did: normalizeDID(record.recipientDID),
+                grantor_did: normalizeDID(record.grantorDID),
+                epoch: record.epoch,
+                sequence: record.sequence,
+                keys_json: adapter.encodeJSON(record.keys),
+                manifest_token: token,
+                delegation_tokens: adapter.encodeJSON(delegationTokens ?? [])
+            };
+            await db.insertInto('kubun_credential_manifests').values(values).onConflict((oc)=>oc.columns([
+                    'owner_did',
+                    'recipient_did',
+                    'grantor_did'
+                ]).doUpdateSet({
+                    epoch: values.epoch,
+                    sequence: values.sequence,
+                    keys_json: values.keys_json,
+                    manifest_token: values.manifest_token,
+                    delegation_tokens: values.delegation_tokens
+                })// Lexicographic: higher epoch always wins; within an epoch,
+                // strictly-greater sequence. A stale/replayed lower value is a silent no-op.
+                .where((eb)=>eb.or([
+                        eb('kubun_credential_manifests.epoch', '<', values.epoch),
+                        eb.and([
+                            eb('kubun_credential_manifests.epoch', '=', values.epoch),
+                            eb('kubun_credential_manifests.sequence', '<', values.sequence)
+                        ])
+                    ]))).execute();
+        },
+        async lockManifestRow (params) {
+            const owner = normalizeDID(params.ownerDID);
+            const recipient = normalizeDID(params.recipientDID);
+            const grantor = normalizeDID(params.grantorDID);
+            await writeAtomically(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();
+            });
+        },
+        async listManifests (params) {
+            const ownerDID = normalizeDID(params.ownerDID);
+            const recipientDID = normalizeDID(params.recipientDID);
+            const rows = await db.selectFrom('kubun_credential_manifests').select([
+                'owner_did',
+                'recipient_did',
+                'grantor_did',
+                'epoch',
+                'sequence',
+                'keys_json',
+                'manifest_token',
+                'delegation_tokens'
+            ]).where('owner_did', '=', ownerDID).where('recipient_did', '=', recipientDID).orderBy('grantor_did', 'asc').execute();
+            return rows.map((row)=>({
+                    record: {
+                        ownerDID: row.owner_did,
+                        recipientDID: row.recipient_did,
+                        grantorDID: row.grantor_did,
+                        epoch: row.epoch,
+                        sequence: row.sequence,
+                        keys: row.keys_json
+                    },
+                    token: row.manifest_token,
+                    delegationTokens: row.delegation_tokens
+                }));
+        },
+        async listDistributableKeys (params) {
+            const owner = normalizeDID(params.ownerDID);
+            const grantor = normalizeDID(params.grantorDID);
+            // One snapshot: active owner keys joined to wrappings at the key's current version.
+            const rows = await db.selectFrom('kubun_credential_keys as k').innerJoin('kubun_credential_wrappings as w', (join)=>join.onRef('w.key_id', '=', 'k.key_id').onRef('w.key_version', '=', 'k.version')).where('k.state', '=', 'active').select([
+                'k.key_id as keyID',
+                'k.version as version',
+                'k.owner_did as ownerDID',
+                'w.recipient_did as recipientDID'
+            ]).execute();
+            const seen = new Set();
+            const out = [];
+            for (const row of rows){
+                if (normalizeDID(row.ownerDID) !== owner) continue;
+                if (row.recipientDID == null || normalizeDID(row.recipientDID) !== grantor) continue;
+                if (seen.has(row.keyID)) continue;
+                seen.add(row.keyID);
+                out.push({
+                    keyID: row.keyID,
+                    version: row.version
+                });
+            }
+            return out;
+        },
+        async beginProvisioningAttempt (params) {
+            const ownerDid = normalizeDID(params.ownerDID);
+            const grantorDid = normalizeDID(params.grantorDID);
+            await writeAtomically(db, async (tx)=>{
+                // Ensure the expectation floor row exists, idempotent at floor 0.
+                await tx.insertInto('kubun_credential_provisioning_expectations').values({
+                    owner_did: ownerDid,
+                    grantor_did: grantorDid,
+                    epoch_floor: 0
+                }).onConflict((oc)=>oc.doNothing()).execute();
+                // Insert the outstanding attempt row, idempotent on the id.
+                await tx.insertInto('kubun_credential_provisioning_attempts').values({
+                    owner_did: ownerDid,
+                    grantor_did: grantorDid,
+                    attempt_id: params.attemptId
+                }).onConflict((oc)=>oc.doNothing()).execute();
+            });
+        },
+        async recordProvisioningAttempt (params) {
+            const ownerDid = normalizeDID(params.ownerDID);
+            const grantorDid = normalizeDID(params.grantorDID);
+            // Single atomic operation: if epoch > heldEpoch, delete attempt and raise floor.
+            let result = {
+                status: 'retry',
+                minEpoch: params.heldEpoch
+            };
+            await writeAtomically(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.
+                    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();
+                    // 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()
+                        })).where('owner_did', '=', ownerDid).where('grantor_did', '=', grantorDid).execute();
+                    result = {
+                        status: 'recorded'
+                    };
+                }
+            });
+            return result;
+        },
+        async abandonProvisioningAttempt (params) {
+            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();
+        },
+        async listProvisioningExpectations (params) {
+            const ownerDid = normalizeDID(params.ownerDID);
+            // Left join expectations to outstanding attempts, grouped by (owner, grantor).
+            // Return one row per (owner, grantor) with floor and outstanding count.
+            const rows = await db.selectFrom('kubun_credential_provisioning_expectations as e').leftJoin('kubun_credential_provisioning_attempts as a', (join)=>join.onRef('a.owner_did', '=', 'e.owner_did').onRef('a.grantor_did', '=', 'e.grantor_did')).select((eb)=>[
+                    'e.grantor_did as grantor_did',
+                    'e.epoch_floor as epoch_floor',
+                    eb.fn.count('a.attempt_id').as('outstanding')
+                ]).where('e.owner_did', '=', ownerDid).groupBy([
+                'e.owner_did',
+                'e.grantor_did',
+                'e.epoch_floor'
+            ]).orderBy('e.grantor_did', 'asc').execute();
+            return rows.map((row)=>({
+                    grantorDID: row.grantor_did,
+                    epochFloor: row.epoch_floor,
+                    outstanding: Number(row.outstanding)
+                }));
+        },
+        async listProvisioningExpectationOwners () {
+            const rows = await db.selectFrom('kubun_credential_provisioning_expectations').select('owner_did').distinct().execute();
+            const owners = new Set();
+            for (const row of rows){
+                owners.add(normalizeDID(row.owner_did));
+            }
+            return [
+                ...owners
+            ];
         }
     };
+    return api;
 }
 /**
  * The ops leaf scan in stamp order — every one, or one key's. Two devices must

package/lib/index.d.ts

@@ -1,8 +1,8 @@
 import type { StoreProvider } from '@kubun/db';
 import type { CredentialStoreAPI } from './api.js';
-export type { CredentialOpInput, CredentialStoreAPI, CredentialTombstoneInput, HeldCredentialSubject, PutCredentialEntryParams, PutCredentialKeyParams, PutCredentialWrappingParams, } 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 { 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, CredentialKey, CredentialKeyBranch, CredentialKeyBranchTable, CredentialKeyState, CredentialKeyTable, CredentialOp, CredentialOpSubjectKind, CredentialOpTable, CredentialTables, CredentialWrapping, CredentialWrappingTable, CredentialWrappingWithBranch, InsertCredentialAlias, InsertCredentialEntry, InsertCredentialKey, InsertCredentialOp, InsertCredentialWrapping, KubunCredentialAliasTable, } from './tables.js';
+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';

package/lib/migrations.js

@@ -49,8 +49,45 @@ export function getCredentialMigrations(ctx) {
                 'namespace',
                 'alias_key'
             ]).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();
+            // Persisted counter minting strictly-increasing refreshSeq, one per (owner, recipient, grantor) triple.
+            await db.schema.createTable('kubun_credential_grantor_counters').ifNotExists().addColumn('owner_did', t.text, (col)=>col.notNull()).addColumn('recipient_did', t.text, (col)=>col.notNull()).addColumn('grantor_did', t.text, (col)=>col.notNull()).addColumn('seq', 'integer', (col)=>col.notNull()).addPrimaryKeyConstraint('pk_kubun_credential_grantor_counters', [
+                'owner_did',
+                'recipient_did',
+                'grantor_did'
+            ]).execute();
+            // Persisted counter minting strictly-increasing provisioning epoch, respecting a minEpoch floor.
+            await db.schema.createTable('kubun_credential_provisioning_epochs').ifNotExists().addColumn('owner_did', t.text, (col)=>col.notNull()).addColumn('recipient_did', t.text, (col)=>col.notNull()).addColumn('grantor_did', t.text, (col)=>col.notNull()).addColumn('epoch', 'integer', (col)=>col.notNull()).addPrimaryKeyConstraint('pk_kubun_credential_provisioning_epochs', [
+                'owner_did',
+                'recipient_did',
+                'grantor_did'
+            ]).execute();
+            // Provisioning expectation floor per (owner, grantor) pair; normalized DIDs.
+            await db.schema.createTable('kubun_credential_provisioning_expectations').ifNotExists().addColumn('owner_did', t.text, (col)=>col.notNull()).addColumn('grantor_did', t.text, (col)=>col.notNull()).addColumn('epoch_floor', 'integer', (col)=>col.notNull().defaultTo(0)).addPrimaryKeyConstraint('pk_kubun_credential_provisioning_expectations', [
+                'owner_did',
+                'grantor_did'
+            ]).execute();
+            // Outstanding provisioning attempts; row exists while in flight, deleted on completion.
+            await db.schema.createTable('kubun_credential_provisioning_attempts').ifNotExists().addColumn('owner_did', t.text, (col)=>col.notNull()).addColumn('grantor_did', t.text, (col)=>col.notNull()).addColumn('attempt_id', t.text, (col)=>col.notNull()).addPrimaryKeyConstraint('pk_kubun_credential_provisioning_attempts', [
+                'owner_did',
+                'grantor_did',
+                'attempt_id'
+            ]).execute();
+            // Grantor-recorded manifests, keyed on the NORMALIZED triple; `(epoch, sequence)` gate every upsert lexicographically.
+            await db.schema.createTable('kubun_credential_manifests').ifNotExists().addColumn('owner_did', t.text, (col)=>col.notNull()).addColumn('recipient_did', t.text, (col)=>col.notNull()).addColumn('grantor_did', t.text, (col)=>col.notNull()).addColumn('epoch', 'integer', (col)=>col.notNull()).addColumn('sequence', 'integer', (col)=>col.notNull()).addColumn('keys_json', t.json, (col)=>col.notNull()).addColumn('manifest_token', t.text, (col)=>col.notNull()).addColumn('delegation_tokens', t.json, (col)=>col.notNull()).addPrimaryKeyConstraint('pk_kubun_credential_manifests', [
+                'owner_did',
+                'recipient_did',
+                'grantor_did'
+            ]).execute();
         },
         async down (db) {
+            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();
+            await db.schema.dropTable('kubun_credential_provisioning_epochs').ifExists().execute();
+            await db.schema.dropTable('kubun_credential_grantor_counters').ifExists().execute();
+            await db.schema.dropTable('kubun_credential_wrapping_authority').ifExists().execute();
             await db.schema.dropTable('kubun_credential_aliases').ifExists().execute();
             await db.schema.dropTable('kubun_credential_ops').ifExists().execute();
             await db.schema.dropTable('kubun_credential_entries').ifExists().execute();

package/lib/tables.d.ts

@@ -166,6 +166,99 @@ export type KubunCredentialAliasTable = {
 };
 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
+ * rather than folded into its content-addressed digest. `refresh_seq` gates
+ * every `put` strictly-greater, so a stale/replayed envelope is a silent no-op.
+ */
+export type CredentialWrappingAuthorityTable = {
+    wrapping_id: string;
+    authority_token: string;
+    refresh_seq: number;
+};
+export type CredentialWrappingAuthority = Selectable<CredentialWrappingAuthorityTable>;
+export type InsertCredentialWrappingAuthority = Insertable<CredentialWrappingAuthorityTable>;
+/**
+ * Monotonic counter minting the strictly-increasing `refreshSeq`, one per
+ * `(ownerDID, recipientDID, grantorDID)` triple. Persisted so a restart never
+ * reissues a sequence number already handed out.
+ */
+export type CredentialGrantorCounterTable = {
+    owner_did: string;
+    recipient_did: string;
+    grantor_did: string;
+    seq: number;
+};
+export type CredentialGrantorCounter = Selectable<CredentialGrantorCounterTable>;
+export type InsertCredentialGrantorCounter = Insertable<CredentialGrantorCounterTable>;
+/**
+ * Monotonic epoch counter minting `nextProvisioningEpoch`, one per
+ * `(ownerDID, recipientDID, grantorDID)` triple, respecting a `minEpoch` floor
+ * for post-rollback recovery. Persisted so a restart never reissues an epoch.
+ */
+export type CredentialProvisioningEpochTable = {
+    owner_did: string;
+    recipient_did: string;
+    grantor_did: string;
+    epoch: number;
+};
+export type CredentialProvisioningEpoch = Selectable<CredentialProvisioningEpochTable>;
+export type InsertCredentialProvisioningEpoch = Insertable<CredentialProvisioningEpochTable>;
+/**
+ * The expectation floor for provisioning a credential manifest: a monotonic
+ * epoch counter gating when a provisioning attempt counts as complete.
+ * Readiness fails closed while an outstanding attempt row exists.
+ */
+export type CredentialProvisioningExpectationTable = {
+    owner_did: string;
+    grantor_did: string;
+    epoch_floor: number;
+};
+export type CredentialProvisioningExpectation = Selectable<CredentialProvisioningExpectationTable>;
+export type InsertCredentialProvisioningExpectation = Insertable<CredentialProvisioningExpectationTable>;
+/**
+ * An outstanding provisioning attempt. Success deletes the row; retry failure
+ * keeps it; abandon deletes it without touching the expectation floor.
+ */
+export type CredentialProvisioningAttemptTable = {
+    owner_did: string;
+    grantor_did: string;
+    attempt_id: string;
+};
+export type CredentialProvisioningAttempt = Selectable<CredentialProvisioningAttemptTable>;
+export type InsertCredentialProvisioningAttempt = Insertable<CredentialProvisioningAttemptTable>;
+/** One key a grantor recorded as granted, as it rides a manifest's `keys_json`. */
+export type CredentialManifestKey = {
+    keyID: string;
+    version: number;
+};
+/**
+ * A grantor's advisory record of the key set it granted one recipient under one
+ * owner — the projection a recipient checks its own store against to prove
+ * completeness (the readiness union). Carries no key material, only ids/versions
+ * and the signed token that authenticated them.
+ *
+ * `(epoch, sequence)` gates every `put` lexicographically: a stale/replayed
+ * value is a silent no-op. `issuedAt` is a drift bound applied on admission,
+ * not persisted here.
+ *
+ * Triple columns are stored NORMALIZED (`normalizeDID`), so a `did:peer:4`
+ * short/long form converges on one row — matching the grantor's write to the
+ * recipient's readiness read.
+ */
+export type CredentialManifestTable = {
+    owner_did: string;
+    recipient_did: string;
+    grantor_did: string;
+    epoch: number;
+    sequence: number;
+    keys_json: JSONArrayColumn<CredentialManifestKey>;
+    manifest_token: string;
+    delegation_tokens: JSONArrayColumn<string>;
+};
+export type CredentialManifest = Selectable<CredentialManifestTable>;
+export type InsertCredentialManifest = Insertable<CredentialManifestTable>;
 export type CredentialTables = {
     kubun_credential_keys: CredentialKeyTable;
     kubun_credential_key_branches: CredentialKeyBranchTable;
@@ -173,5 +266,11 @@ export type CredentialTables = {
     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;
+    kubun_credential_provisioning_expectations: CredentialProvisioningExpectationTable;
+    kubun_credential_provisioning_attempts: CredentialProvisioningAttemptTable;
+    kubun_credential_manifests: CredentialManifestTable;
 };
 export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kubun/store-credential",
-  "version": "0.14.0",
+  "version": "0.15.0",
   "keywords": [],
   "license": "see LICENSE.md",
   "sideEffects": false,
@@ -16,13 +16,13 @@
   ],
   "dependencies": {
     "@kokuin/token": "^0.5.0",
-    "@kubun/db": "^0.14.0",
-    "@kubun/db-adapter": "^0.14.0",
+    "@kubun/db": "^0.15.0",
+    "@kubun/db-adapter": "^0.15.0",
     "kysely": "^0.29.5"
   },
   "devDependencies": {
-    "@kubun/db-better-sqlite": "^0.14.0",
-    "@kubun/db-postgres": "^0.14.0",
+    "@kubun/db-better-sqlite": "^0.15.0",
+    "@kubun/db-postgres": "^0.15.0",
     "@testcontainers/postgresql": "^12.1.0"
   },
   "publishConfig": {