@kubun/store-credential 0.17.4 → 0.18.0

package/lib/api-provisioning.js

@@ -0,0 +1,227 @@
+import { normalizeDID } from '@kokuin/token';
+export function createProvisioningApi(ctx) {
+    const { db, adapter, writeAmbient } = ctx;
+    return {
+        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 (params) {
+            const { record, token, delegationTokens } = params;
+            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 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();
+            });
+        },
+        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.owner_did', '=', 'k.owner_did').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 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,
+                    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 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.
+                    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 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);
+            // 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
+            ];
+        }
+    };
+}

package/lib/api-records.d.ts

@@ -0,0 +1,3 @@
+import type { CredentialStoreAPI } from './api-types.js';
+import type { StoreContext } from './store-context.js';
+export declare function createRecordsApi(ctx: StoreContext): Pick<CredentialStoreAPI, 'getRecordRow' | 'getRecordRows' | 'getRecordRowsForKeys' | 'deleteRecordCopy' | 'listRecordRows' | 'putRecord' | 'retainEntryCandidate' | 'listRevocations'>;

package/lib/api-records.js

@@ -0,0 +1,74 @@
+import { chunked } from '@kubun/db-adapter';
+import { recordKeyText, verifySignedRecord } from '@kubun/records';
+import { putCredentialRecord, retainCredentialEntryCandidate } from './records.js';
+export function createRecordsApi(ctx) {
+    const { db, adapter, oneOwner, verifiedCopies, writeAmbient, lockKeyRowInTransaction } = ctx;
+    return {
+        async getRecordRow (type, id) {
+            return await db.selectFrom('kubun_credential_records').selectAll().where('type', '=', type).where('id', '=', id).executeTakeFirst();
+        },
+        async getRecordRows (key) {
+            return await db.selectFrom('kubun_credential_records').selectAll().where('type', '=', key.type).where('owner', '=', key.owner).where('id', '=', key.id).orderBy('op_hash', 'asc').execute();
+        },
+        async getRecordRowsForKeys (keys) {
+            const wanted = new Set();
+            const idsByType = new Map();
+            for (const key of keys){
+                wanted.add(recordKeyText(key));
+                const ids = idsByType.get(key.type) ?? new Set();
+                ids.add(key.id);
+                idsByType.set(key.type, ids);
+            }
+            const rowsByKey = new Map();
+            for (const [type, idSet] of idsByType){
+                const ids = [
+                    ...idSet
+                ];
+                for (const chunk of chunked(ids)){
+                    const rows = await db.selectFrom('kubun_credential_records').selectAll().where('type', '=', type).where('id', 'in', chunk).orderBy('op_hash', 'asc').execute();
+                    for (const row of rows){
+                        const text = recordKeyText(row);
+                        if (!wanted.has(text)) continue;
+                        const group = rowsByKey.get(text) ?? [];
+                        group.push(row);
+                        rowsByKey.set(text, group);
+                    }
+                }
+            }
+            return rowsByKey;
+        },
+        async deleteRecordCopy (key, opHash) {
+            await db.deleteFrom('kubun_credential_records').where('type', '=', key.type).where('owner', '=', key.owner).where('id', '=', key.id).where('op_hash', '=', opHash).execute();
+        },
+        async listRecordRows (types) {
+            if (types.length === 0) return [];
+            return await db.selectFrom('kubun_credential_records').selectAll().where('type', 'in', [
+                ...types
+            ]).orderBy('type', 'asc').orderBy('owner', 'asc').orderBy('id', 'asc').orderBy('op_hash', 'asc').execute();
+        },
+        async putRecord (record, methods) {
+            await putCredentialRecord({
+                record,
+                methods,
+                verifiedCopies: db.isTransaction ? verifiedCopies : new Map(),
+                adapter,
+                write: (fn)=>writeAmbient(db, fn),
+                lockKey: lockKeyRowInTransaction
+            });
+        },
+        async retainEntryCandidate (record, methods) {
+            const op = await verifySignedRecord(record, methods);
+            if (op === null || record.type !== 'credential.entry') {
+                throw new Error('Cannot retain an unverified credential entry');
+            }
+            await writeAmbient(db, async (tx)=>{
+                await retainCredentialEntryCandidate(tx, record, op.claim, adapter);
+            });
+        },
+        async listRevocations (keyID, ownerDID) {
+            let query = db.selectFrom('kubun_credential_revocations').selectAll().where('key_id', '=', keyID);
+            if (ownerDID !== undefined) query = query.where('owner_did', '=', ownerDID);
+            return oneOwner(await query.orderBy('recipient_did', 'asc').execute(), `revocations ${keyID}`);
+        }
+    };
+}