@kokuin/store-vault 0.0.0-stage → 0.1.0

package/lib/batch.d.ts

@@ -0,0 +1,89 @@
+import type { Insertable, Kysely } from '@hozon/db';
+import type { VaultKeyBranchTable, VaultRecordsTables } from './record-tables.js';
+import type { VaultEntryTable, VaultStoreTables, VaultWrappingTable } from './tables.js';
+/**
+ * Bound parameters allowed in one statement. Well under SQLite's oldest default limit (999) and
+ * Postgres's (65535), and the cap the store's own reads keep to.
+ */
+export declare const PARAMETER_BUDGET = 500;
+/** Splits `items` so no statement binds more than `PARAMETER_BUDGET` parameters. */
+export declare function statementChunks<Item>(items: Iterable<Item>, parametersPerItem: number): Array<Array<Item>>;
+export type WrappingValues = Insertable<Omit<VaultWrappingTable, 'mode'>>;
+export type EntryValues = Insertable<Omit<VaultEntryTable, 'mode'>>;
+export type WrappingKey = {
+    owner_did: string;
+    wrapping_id: string;
+};
+export type EntryKey = {
+    owner_did: string;
+    entry_id: string;
+};
+export type DecisionKey = {
+    type: string;
+    owner: string;
+    id: string;
+};
+/** Parameters each row binds. */
+export declare const WRAPPING_COLUMNS = 10;
+export declare const ENTRY_COLUMNS = 11;
+export declare const DECISION_COLUMNS = 6;
+export declare const KEY_BRANCH_COLUMNS = 6;
+/**
+ * One multi-row upsert. A row whose stored wrapping belongs to another key is left alone and
+ * not counted, as the single-row upsert does.
+ */
+export declare function upsertWrappings(db: Kysely<VaultStoreTables>, rows: Array<WrappingValues>): import("kysely").InsertQueryBuilder<VaultStoreTables, "vault_wrappings", import("kysely").InsertResult>;
+/** As `upsertWrappings`, for entries. */
+export declare function upsertEntries(db: Kysely<VaultStoreTables>, rows: Array<EntryValues>): import("kysely").InsertQueryBuilder<VaultStoreTables, "vault_entries", import("kysely").InsertResult>;
+export declare function selectWrappings(db: Kysely<VaultStoreTables>, keys: Array<WrappingKey>): import("@hozon/db").SelectQueryBuilder<VaultStoreTables, "vault_wrappings", {
+    mode: "local" | "replicated";
+    owner_did: string;
+    wrapping_id: string;
+    key_id: string;
+    key_version: number;
+    descriptors: import("@kokuin/vault").FactorDescriptor[];
+    descriptor_digest: string;
+    iv: Uint8Array<ArrayBufferLike>;
+    wrapped_key: Uint8Array<ArrayBufferLike>;
+    recipient_did: string | null;
+    provenance: string;
+}>;
+export declare function selectEntries(db: Kysely<VaultStoreTables>, keys: Array<EntryKey>): import("@hozon/db").SelectQueryBuilder<VaultStoreTables, "vault_entries", {
+    mode: "local" | "replicated";
+    owner_did: string;
+    key_id: string;
+    key_version: number;
+    iv: Uint8Array<ArrayBufferLike>;
+    provenance: string;
+    entry_id: string;
+    kind: string;
+    label: string;
+    attributes: Record<string, string>;
+    ciphertext: Uint8Array<ArrayBufferLike>;
+    hlc: string;
+}>;
+/** Deletes each wrapping only while it still belongs to the named key. */
+export declare function deleteWrappingRows(db: Kysely<VaultStoreTables>, rows: Array<WrappingKey & {
+    key_id: string;
+}>): import("kysely").DeleteQueryBuilder<VaultStoreTables, "vault_wrappings", import("kysely").DeleteResult>;
+/** Deletes each entry only while it still belongs to the named key. */
+export declare function deleteEntryRows(db: Kysely<VaultStoreTables>, rows: Array<EntryKey & {
+    key_id: string;
+}>): import("kysely").DeleteQueryBuilder<VaultStoreTables, "vault_entries", import("kysely").DeleteResult>;
+export declare function insertDecisionClaims(db: Kysely<VaultRecordsTables>, keys: Array<DecisionKey>, mode: 'local' | 'replicated'): import("kysely").InsertQueryBuilder<VaultRecordsTables, "vault_decisions", import("kysely").InsertResult>;
+export declare function selectDecisionModes(db: Kysely<VaultRecordsTables>, keys: Array<DecisionKey>): import("@hozon/db").SelectQueryBuilder<VaultRecordsTables, "vault_decisions", {
+    mode: "local" | "replicated";
+    type: string;
+    owner: string;
+    id: string;
+}>;
+/**
+ * Claims a record key for replicated mode and records its decision, in one statement. A key held
+ * in local mode is left alone and counts no row.
+ */
+export declare function upsertReplicatedDecision(db: Kysely<VaultRecordsTables>, decision: DecisionKey & {
+    content_digest: string;
+    decision_hlc: string;
+}): import("kysely").InsertQueryBuilder<VaultRecordsTables, "vault_decisions", import("kysely").InsertResult>;
+/** One multi-row upsert of key-branch projection rows. A record ID moves to its new key. */
+export declare function upsertKeyBranches(db: Kysely<VaultRecordsTables>, rows: Array<VaultKeyBranchTable>): import("kysely").InsertQueryBuilder<VaultRecordsTables, "vault_key_branches", import("kysely").InsertResult>;

package/lib/batch.js

@@ -0,0 +1,159 @@
+import { chunk } from '@hozon/db';
+/**
+ * Bound parameters allowed in one statement. Well under SQLite's oldest default limit (999) and
+ * Postgres's (65535), and the cap the store's own reads keep to.
+ */ export const PARAMETER_BUDGET = 500;
+/** Splits `items` so no statement binds more than `PARAMETER_BUDGET` parameters. */ export function statementChunks(items, parametersPerItem) {
+    return chunk(items, Math.max(1, Math.floor(PARAMETER_BUDGET / parametersPerItem)));
+}
+/** Parameters each row binds. */ export const WRAPPING_COLUMNS = 10;
+export const ENTRY_COLUMNS = 11;
+export const DECISION_COLUMNS = 6;
+export const KEY_BRANCH_COLUMNS = 6;
+/**
+ * One multi-row upsert. A row whose stored wrapping belongs to another key is left alone and
+ * not counted, as the single-row upsert does.
+ */ export function upsertWrappings(db, rows) {
+    return db.insertInto('vault_wrappings').values(rows).onConflict((oc)=>{
+        return oc.columns([
+            'owner_did',
+            'wrapping_id'
+        ]).doUpdateSet((eb)=>{
+            return {
+                key_id: eb.ref('excluded.key_id'),
+                key_version: eb.ref('excluded.key_version'),
+                descriptors: eb.ref('excluded.descriptors'),
+                descriptor_digest: eb.ref('excluded.descriptor_digest'),
+                iv: eb.ref('excluded.iv'),
+                wrapped_key: eb.ref('excluded.wrapped_key'),
+                recipient_did: eb.ref('excluded.recipient_did'),
+                provenance: eb.ref('excluded.provenance')
+            };
+        }).where((eb)=>eb('vault_wrappings.key_id', '=', eb.ref('excluded.key_id')));
+    });
+}
+/** As `upsertWrappings`, for entries. */ export function upsertEntries(db, rows) {
+    return db.insertInto('vault_entries').values(rows).onConflict((oc)=>{
+        return oc.columns([
+            'owner_did',
+            'entry_id'
+        ]).doUpdateSet((eb)=>{
+            return {
+                key_id: eb.ref('excluded.key_id'),
+                key_version: eb.ref('excluded.key_version'),
+                kind: eb.ref('excluded.kind'),
+                label: eb.ref('excluded.label'),
+                attributes: eb.ref('excluded.attributes'),
+                iv: eb.ref('excluded.iv'),
+                ciphertext: eb.ref('excluded.ciphertext'),
+                hlc: eb.ref('excluded.hlc'),
+                provenance: eb.ref('excluded.provenance')
+            };
+        }).where((eb)=>eb('vault_entries.key_id', '=', eb.ref('excluded.key_id')));
+    });
+}
+export function selectWrappings(db, keys) {
+    return db.selectFrom('vault_wrappings').selectAll().where((eb)=>{
+        return eb.or(keys.map((key)=>{
+            return eb.and([
+                eb('owner_did', '=', key.owner_did),
+                eb('wrapping_id', '=', key.wrapping_id)
+            ]);
+        }));
+    });
+}
+export function selectEntries(db, keys) {
+    return db.selectFrom('vault_entries').selectAll().where((eb)=>{
+        return eb.or(keys.map((key)=>{
+            return eb.and([
+                eb('owner_did', '=', key.owner_did),
+                eb('entry_id', '=', key.entry_id)
+            ]);
+        }));
+    });
+}
+/** Deletes each wrapping only while it still belongs to the named key. */ export function deleteWrappingRows(db, rows) {
+    return db.deleteFrom('vault_wrappings').where((eb)=>{
+        return eb.or(rows.map((row)=>{
+            return eb.and([
+                eb('owner_did', '=', row.owner_did),
+                eb('wrapping_id', '=', row.wrapping_id),
+                eb('key_id', '=', row.key_id)
+            ]);
+        }));
+    });
+}
+/** Deletes each entry only while it still belongs to the named key. */ export function deleteEntryRows(db, rows) {
+    return db.deleteFrom('vault_entries').where((eb)=>{
+        return eb.or(rows.map((row)=>{
+            return eb.and([
+                eb('owner_did', '=', row.owner_did),
+                eb('entry_id', '=', row.entry_id),
+                eb('key_id', '=', row.key_id)
+            ]);
+        }));
+    });
+}
+export function insertDecisionClaims(db, keys, mode) {
+    return db.insertInto('vault_decisions').values(keys.map((key)=>{
+        return {
+            ...key,
+            mode,
+            content_digest: null,
+            decision_hlc: null
+        };
+    })).onConflict((oc)=>oc.columns([
+            'type',
+            'owner',
+            'id'
+        ]).doNothing());
+}
+export function selectDecisionModes(db, keys) {
+    return db.selectFrom('vault_decisions').select([
+        'type',
+        'owner',
+        'id',
+        'mode'
+    ]).where((eb)=>{
+        return eb.or(keys.map((key)=>{
+            return eb.and([
+                eb('type', '=', key.type),
+                eb('owner', '=', key.owner),
+                eb('id', '=', key.id)
+            ]);
+        }));
+    });
+}
+/**
+ * Claims a record key for replicated mode and records its decision, in one statement. A key held
+ * in local mode is left alone and counts no row.
+ */ export function upsertReplicatedDecision(db, decision) {
+    return db.insertInto('vault_decisions').values({
+        ...decision,
+        mode: 'replicated'
+    }).onConflict((oc)=>{
+        return oc.columns([
+            'type',
+            'owner',
+            'id'
+        ]).doUpdateSet({
+            content_digest: decision.content_digest,
+            decision_hlc: decision.decision_hlc
+        }).where('vault_decisions.mode', '=', 'replicated');
+    });
+}
+/** One multi-row upsert of key-branch projection rows. A record ID moves to its new key. */ export function upsertKeyBranches(db, rows) {
+    return db.insertInto('vault_key_branches').values(rows).onConflict((oc)=>{
+        return oc.columns([
+            'owner_did',
+            'record_id'
+        ]).doUpdateSet((eb)=>{
+            return {
+                key_id: eb.ref('excluded.key_id'),
+                key_version: eb.ref('excluded.key_version'),
+                branch_id: eb.ref('excluded.branch_id'),
+                op_jwt: eb.ref('excluded.op_jwt')
+            };
+        });
+    });
+}

package/lib/coordinator-context.d.ts

@@ -0,0 +1,71 @@
+import type { RecordKey, SignedRecord, VerifiedRecordOp } from '@kokuin/records';
+import type { KeyCache, VaultRecordMetas, VaultRecordPayloads, VaultRecordType } from '@kokuin/vault';
+import type { CoordinatorCall, VaultCoordinatorParams } from './coordinator-types.js';
+import type { VaultKeyBranch, VaultRecords, VaultWritePreconditions } from './records.js';
+import type { KeyAddress, KeyRow, VaultStoreAPI, WrappingRow } from './types.js';
+export declare class VaultNotAuthorized extends Error {
+    constructor(verb: 'read' | 'administer');
+}
+export declare class VaultNotFound extends Error {
+    constructor();
+}
+export declare class VaultRepairPending extends Error {
+    constructor();
+}
+export declare class VaultSupersededBranch extends Error {
+    constructor();
+}
+export declare class VaultKeyLocked extends Error {
+    constructor();
+}
+export type StoredRecordEvidence = {
+    record: SignedRecord;
+    op: VerifiedRecordOp;
+};
+export type WrappingEvidence = StoredRecordEvidence & {
+    expectedDescriptorDigest: string;
+};
+export type KeyBranch = {
+    branchID: string;
+    branchRecordID: string;
+    suite: number;
+};
+export type KeyRecords = {
+    records: Array<SignedRecord>;
+    branchID: string;
+    branchRecordID: string;
+};
+export type CoordinatorContext = {
+    params: VaultCoordinatorParams;
+    cache: KeyCache;
+    cacheID(address: KeyAddress): string;
+    records: VaultRecords | undefined;
+    recordsFor(store: VaultStoreAPI): VaultRecords;
+    authorize(operation: string, verb: 'read' | 'administer', address: {
+        ownerDID: string;
+        keyID?: string;
+        entryID?: string;
+    } & CoordinatorCall, store?: VaultStoreAPI): Promise<void>;
+    key(address: KeyAddress, store?: VaultStoreAPI): Promise<KeyRow>;
+    signed<Type extends VaultRecordType>(type: Type, address: {
+        ownerDID: string;
+        id: string;
+    }, payload: VaultRecordPayloads[Type] | null, meta: VaultRecordMetas[Type], hlc?: string): Promise<SignedRecord>;
+    verified(record: SignedRecord): Promise<VerifiedRecordOp>;
+    stored(address: RecordKey, store?: VaultStoreAPI): Promise<StoredRecordEvidence>;
+    /** One batched read. Throws the first missing or unverifiable record in address order. */
+    storedMany(addresses: ReadonlyArray<RecordKey>, store?: VaultStoreAPI): Promise<Array<StoredRecordEvidence>>;
+    wrappingEvidence(row: WrappingRow, store?: VaultStoreAPI): Promise<WrappingEvidence | undefined>;
+    /** Replicated evidence for each row, in row order, from one batched read. Empty in local mode. */
+    wrappingEvidences(rows: ReadonlyArray<WrappingRow>, store?: VaultStoreAPI): Promise<Array<WrappingEvidence>>;
+    branches(address: KeyAddress, version: number, store?: VaultStoreAPI): Promise<Array<VaultKeyBranch>>;
+    branch(address: KeyAddress, version: number, store?: VaultStoreAPI, specific?: string): Promise<KeyBranch>;
+    write(store: VaultStoreAPI, output: Array<SignedRecord>, preconditions: VaultWritePreconditions, call: CoordinatorCall): Promise<void>;
+    keyRecords(row: KeyRow, store: VaultStoreAPI, unique?: string, consumer?: unknown): Promise<KeyRecords>;
+    locked<Result>(addresses: ReadonlyArray<KeyAddress>, fn: (store: VaultStoreAPI) => Promise<Result>): Promise<Result>;
+    read<Result>(fn: (store: VaultStoreAPI) => Promise<Result>): Promise<Result>;
+    evict(address: KeyAddress): void;
+    evictAll(ownerDID: string): void;
+    generation(address: KeyAddress): string;
+};
+export declare function createCoordinatorContext(params: VaultCoordinatorParams): CoordinatorContext;