@kokuin/store-vault 0.0.0-stage → 0.1.0

package/lib/records-rows.js

@@ -0,0 +1,155 @@
+import { chunk, withStoreTransaction } from '@hozon/db';
+import { recordClaimDigest, recordKeyText, recordPayloadMatches, verifySignedRecord } from '@kokuin/records';
+import { decodeVaultRecord, VAULT_RECORD_TYPES } from '@kokuin/vault';
+import { PARAMETER_BUDGET } from './batch.js';
+import { settleAll } from './settle.js';
+export class VaultRecordRowError extends Error {
+    #type;
+    #id;
+    constructor(key){
+        super(`Stored vault record ${key.type} ${key.id} is corrupt`, {
+            cause: key.cause
+        });
+        this.name = 'VaultRecordRowError';
+        this.#type = key.type;
+        this.#id = key.id;
+    }
+    get type() {
+        return this.#type;
+    }
+    get id() {
+        return this.#id;
+    }
+}
+// Keyed OR predicates per getMany statement, within SQLite's default bind limit.
+export const GET_MANY_CHUNK = 160;
+export const boundAdapters = new WeakMap();
+export const acceptedKinds = new WeakMap();
+export function supported(type) {
+    return VAULT_RECORD_TYPES.includes(type);
+}
+export function json(value) {
+    return typeof value === 'string' ? JSON.parse(value) : value;
+}
+export function groupRows(rows) {
+    const groups = new Map();
+    for (const row of rows){
+        const key = recordKeyText(row);
+        const group = groups.get(key) ?? [];
+        group.push(row);
+        groups.set(key, group);
+    }
+    return groups;
+}
+/** Deletes the named copies of one record, in statements of at most `PARAMETER_BUDGET` binds. */ export async function deleteCopies(db, key, opHashes) {
+    await settleAll(// Three binds name the record. The rest name copies.
+    chunk(opHashes, PARAMETER_BUDGET - 3).map((part)=>{
+        return db.deleteFrom('vault_records').where('type', '=', key.type).where('owner', '=', key.owner).where('id', '=', key.id).where('op_hash', 'in', part).execute();
+    }));
+}
+export function whereKey(db, key) {
+    return db.selectFrom('vault_records').selectAll().where('type', '=', key.type).where('owner', '=', key.owner).where('id', '=', key.id);
+}
+export async function assertDomain(bound) {
+    // The domain row is written once, in its own committed transaction, and never changed. Once it
+    // matches, it matches for the bound adapter's lifetime.
+    if (bound.domainChecked === true) return;
+    const row = await withStoreTransaction(bound.db, (db)=>{
+        return db.selectFrom('vault_record_domain').selectAll().executeTakeFirst();
+    });
+    if (row === undefined) throw new Error('Initialise the vault operation kind outside caller transactions');
+    if (row.op_kind !== bound.opKind) throw new TypeError('Vault records store belongs to another operation kind');
+    bound.domainChecked = true;
+}
+export async function checked(row, bound) {
+    const key = {
+        type: row.type,
+        owner: row.owner,
+        id: row.id
+    };
+    try {
+        if (row.deleted !== 0 && row.deleted !== 1) throw new Error('invalid deleted flag');
+        const payload = row.payload === null ? null : Uint8Array.from(row.payload);
+        if (row.deleted === 1 !== (payload === null)) throw new Error('invalid payload liveness');
+        const meta = json(row.meta);
+        if (meta === null || typeof meta !== 'object' || Array.isArray(meta)) throw new Error('invalid metadata');
+        const copy = {
+            ...key,
+            hlc: row.hlc,
+            opJWT: row.op_jwt,
+            opHash: row.op_hash,
+            payload
+        };
+        const op = await verifySignedRecord(copy, bound.opKind, bound.params.methods);
+        if (op === null) return null;
+        if (!recordPayloadMatches(copy, op.claim) || row.payload_digest !== op.claim.payloadDigest || row.deleted !== Number(op.claim.deleted) || recordClaimDigest({
+            ...op.claim,
+            meta: meta
+        }) !== recordClaimDigest(op.claim)) throw new Error('stored claim mismatch');
+        if (!op.claim.deleted) decodeVaultRecord(copy, op.claim.meta);
+        return {
+            copy,
+            op
+        };
+    } catch (cause) {
+        // biome-ignore lint/style/useErrorCause: the constructor forwards cause
+        throw new VaultRecordRowError({
+            ...key,
+            cause
+        });
+    }
+}
+export async function decision(rows, bound) {
+    const copies = [];
+    let selected;
+    let failure;
+    // Checks run together. Results are consumed in row order, as the sequential checks were.
+    const results = await Promise.allSettled(rows.map((row)=>checked(row, bound)));
+    for (const result of results){
+        if (result.status === 'rejected') {
+            failure ??= result.reason;
+            continue;
+        }
+        const value = result.value;
+        if (value === null) continue;
+        const contentDigest = recordClaimDigest(value.op.claim);
+        const decisionHLC = typeof value.op.claim.meta.version === 'string' ? value.op.claim.meta.version : value.op.claim.hlc;
+        if (selected !== undefined && (selected.contentDigest !== contentDigest || selected.decisionHLC !== decisionHLC)) throw new VaultRecordRowError(value.copy);
+        selected = {
+            contentDigest,
+            decisionHLC
+        };
+        copies.push(value.copy);
+    }
+    if (selected === undefined) {
+        if (failure !== undefined) throw failure;
+        // Invalid signatures cannot make an existing decision appear absent.
+        if (rows[0] !== undefined) throw new VaultRecordRowError(rows[0]);
+        return null;
+    }
+    const first = copies[0];
+    if (first === undefined) return null;
+    return {
+        key: {
+            type: first.type,
+            owner: first.owner,
+            id: first.id
+        },
+        ...selected,
+        copies: copies.sort((a, b)=>a.opHash.localeCompare(b.opHash))
+    };
+}
+export function values(record, op, bound) {
+    return {
+        type: record.type,
+        owner: record.owner,
+        id: record.id,
+        hlc: record.hlc,
+        op_jwt: record.opJWT,
+        op_hash: record.opHash,
+        payload: record.payload === null ? null : bound.adapter.encodeBinary(record.payload),
+        payload_digest: op.claim.payloadDigest,
+        deleted: Number(op.claim.deleted),
+        meta: bound.adapter.encodeJSON(op.claim.meta)
+    };
+}

package/lib/records.d.ts

@@ -0,0 +1,59 @@
+import type { ApplyRecordChunkParams, ApplyResult, RecordStoreAdapter, SignedRecord, VerifiedRecordOp } from '@kokuin/records';
+import type { VaultRecordTypeParams } from '@kokuin/vault';
+import type { EntryAddress, KeyAddress, VaultStoreAPI, WrappingRow } from './types.js';
+export { vaultRecordPortsFor } from './records-ports.js';
+export { VaultRecordRowError } from './records-rows.js';
+export type VaultWritePreconditions = {
+    key?: KeyAddress & {
+        expectedVersion: number | null;
+        expectedBranches?: ReadonlyArray<string>;
+    };
+    entry?: EntryAddress & {
+        expectedHLC: string | null;
+    };
+};
+export type VaultRecordsParams = Omit<VaultRecordTypeParams, 'portsFor'> & {
+    store: VaultStoreAPI;
+    nowMS: () => number;
+    maxDriftMS: number;
+    receiveClock?: ApplyRecordChunkParams['receiveClock'];
+    onCorruptRow?: (info: {
+        type: string;
+        id: string;
+        error: unknown;
+    }) => void;
+};
+export type VaultKeyBranch = {
+    branchID: string;
+    /** The `vault.key-branch` record that projected this branch. */
+    branchRecordID: string;
+    introducingOp: VerifiedRecordOp;
+};
+export type VaultRecords = {
+    adapter: RecordStoreAdapter;
+    apply(records: ReadonlyArray<SignedRecord>, transportContext?: unknown): Promise<ApplyResult>;
+    write(params: {
+        records: ReadonlyArray<SignedRecord>;
+        preconditions: VaultWritePreconditions;
+        transportContext?: unknown;
+    }): Promise<ApplyResult>;
+    listKeyBranches(address: KeyAddress & {
+        keyVersion: number;
+    }): Promise<Array<VaultKeyBranch>>;
+    /**
+     * Rewrites the key's branch projection from its stored, verified `vault.key-branch` records.
+     * Writes only when the projection differs. Returns whether it did.
+     */
+    rebuildKeyBranches(address: KeyAddress): Promise<boolean>;
+    listWrappingsWithBranch(address: KeyAddress & {
+        keyVersion?: number;
+    }): Promise<Array<WrappingRow>>;
+    listEntryCandidates(address: KeyAddress & {
+        keyVersion: number;
+    }): Promise<Array<SignedRecord>>;
+    listPriorEntryTombstones(address: KeyAddress & {
+        beforeVersion: number;
+    }): Promise<Array<SignedRecord>>;
+    listRevocations(address: KeyAddress): Promise<Array<string>>;
+};
+export declare function createVaultRecords(params: VaultRecordsParams): VaultRecords;

package/lib/records.js

@@ -0,0 +1,233 @@
+import { withStoreTransaction } from '@hozon/db';
+import { applyRecordChunk, getRecordDecisions, recordKeyText, verifyRecordOp, verifySignedRecord } from '@kokuin/records';
+import { decodeVaultRecord, vaultRecordTypes } from '@kokuin/vault';
+import { KEY_BRANCH_COLUMNS, statementChunks, upsertKeyBranches } from './batch.js';
+import { VaultWriteConflict, vaultDatabases } from './record-context.js';
+import { makeAdapter } from './records-adapter.js';
+import { vaultRecordPortsFor } from './records-ports.js';
+import { acceptedKinds, assertDomain, boundAdapters, checked, VaultRecordRowError } from './records-rows.js';
+import { settleAll, settledValue } from './settle.js';
+export { vaultRecordPortsFor } from './records-ports.js';
+export { VaultRecordRowError } from './records-rows.js';
+export function createVaultRecords(params) {
+    if (typeof params.opKind !== 'string' || params.opKind.length === 0) throw new TypeError('An explicit operation kind is required');
+    const storage = vaultDatabases.get(params.store);
+    if (storage === undefined || !storage.context.provider.hasStore('vault-records')) throw new Error('Register the optional vault records store first');
+    const existingKind = acceptedKinds.get(params.store);
+    if (existingKind !== undefined && existingKind !== params.opKind) throw new TypeError('Vault records store belongs to another operation kind');
+    acceptedKinds.set(params.store, params.opKind);
+    const bound = {
+        ...storage,
+        params,
+        opKind: params.opKind,
+        store: params.store
+    };
+    const adapter = makeAdapter(bound);
+    const types = vaultRecordTypes({
+        ...params,
+        portsFor: vaultRecordPortsFor
+    });
+    const apply = (records, store, transportContext)=>{
+        return applyRecordChunk({
+            records,
+            store,
+            types,
+            opKind: params.opKind,
+            nowMS: params.nowMS(),
+            maxDriftMS: params.maxDriftMS,
+            receiveClock: params.receiveClock ?? (()=>{}),
+            methods: params.methods,
+            transportContext,
+            resolveController: async ()=>null,
+            verifyCapability: async ()=>false
+        });
+    };
+    const candidates = async (address, version, prior)=>{
+        await assertDomain(bound);
+        return withStoreTransaction(bound.db, async (tx)=>{
+            let query = tx.selectFrom('vault_entry_candidates').selectAll().where('owner', '=', address.ownerDID).where('key_id', '=', address.keyID);
+            query = prior ? query.where('key_version', '<', version).where('deleted', '=', 1) : query.where('key_version', '=', version);
+            const rows = await query.orderBy('id').orderBy('op_hash').execute();
+            return settleAll(rows.map(async (row)=>{
+                const value = await checked(row, bound);
+                if (value === null) throw new VaultRecordRowError(row);
+                return value.copy;
+            }));
+        });
+    };
+    const api = {
+        adapter,
+        apply: (records, transportContext)=>apply(records, adapter, transportContext),
+        async write (request) {
+            if (request.preconditions === undefined) throw new TypeError('Signed writes require explicit preconditions');
+            return adapter.transaction(async (tx)=>{
+                const inner = boundAdapters.get(tx);
+                if (inner === undefined) throw new Error('Missing transaction adapter');
+                const expectedKey = request.preconditions.key;
+                const expectedEntry = request.preconditions.entry;
+                if (expectedKey === undefined && expectedEntry === undefined) throw new TypeError('Signed writes require a key or entry precondition');
+                // The address precondition reads nothing, so it runs before any store read, as it did.
+                const ops = await settleAll(request.records.map(async (record)=>{
+                    const op = await verifySignedRecord(record, params.opKind, params.methods);
+                    if (op !== null && !(expectedKey !== undefined && expectedKey.ownerDID === op.claim.owner && expectedKey.keyID === op.claim.meta.keyID || expectedEntry !== undefined && record.type === 'vault.entry' && expectedEntry.ownerDID === record.owner && expectedEntry.entryID === record.id)) throw new TypeError('Every signed output requires an address precondition');
+                    return op;
+                }));
+                const [old, observedEntry] = await settleAll([
+                    getRecordDecisions(tx, request.records),
+                    expectedEntry === undefined ? Promise.resolve(undefined) : inner.store.getEntry(expectedEntry)
+                ]);
+                const recordAddresses = await settleAll(request.records.map(async (record, position)=>{
+                    const op = ops[position] ?? null;
+                    const found = [];
+                    if (op !== null && typeof op.claim.meta.keyID === 'string') found.push({
+                        ownerDID: record.owner,
+                        keyID: op.claim.meta.keyID
+                    });
+                    const copies = old.get(recordKeyText(record))?.copies ?? [];
+                    const priors = await settleAll(copies.map((copy)=>verifySignedRecord(copy, params.opKind, params.methods)));
+                    for (const [index, prior] of priors.entries()){
+                        const copy = copies[index];
+                        if (copy !== undefined && typeof prior?.claim.meta.keyID === 'string') found.push({
+                            ownerDID: copy.owner,
+                            keyID: prior.claim.meta.keyID
+                        });
+                    }
+                    return found;
+                }));
+                const addresses = recordAddresses.flat();
+                if (expectedKey !== undefined) addresses.push(expectedKey);
+                if (observedEntry !== undefined) addresses.push(observedEntry);
+                await tx.lock?.(addresses.map((address)=>{
+                    return {
+                        type: 'vault.key',
+                        key: JSON.stringify([
+                            address.ownerDID,
+                            address.keyID
+                        ])
+                    };
+                }));
+                const heldKeys = new Set(addresses.map((address)=>JSON.stringify([
+                        address.ownerDID,
+                        address.keyID
+                    ])));
+                // Authoritative reads follow the lock. They are independent of each other.
+                const keyCheck = async ()=>{
+                    if (expectedKey === undefined) return true;
+                    const row = await inner.store.getKey(expectedKey);
+                    if ((row?.version ?? null) !== expectedKey.expectedVersion) return false;
+                    if (expectedKey.expectedBranches === undefined) return true;
+                    const branches = await createVaultRecords({
+                        ...params,
+                        store: inner.store
+                    }).listKeyBranches({
+                        ...expectedKey,
+                        keyVersion: expectedKey.expectedVersion ?? 0
+                    });
+                    const current = branches.map((branch)=>branch.branchID).sort();
+                    const expected = [
+                        ...expectedKey.expectedBranches
+                    ].sort();
+                    return JSON.stringify(current) === JSON.stringify(expected);
+                };
+                // All three run together. Results are checked in the old order: held copies, entry key,
+                // key version and branches, entry HLC.
+                const [currentRead, entryRead, keyRead] = await Promise.allSettled([
+                    getRecordDecisions(tx, request.records),
+                    expectedEntry === undefined ? Promise.resolve(undefined) : inner.store.getEntry(expectedEntry),
+                    keyCheck()
+                ]);
+                const current = settledValue(currentRead);
+                const currentOps = await settleAll(request.records.flatMap((record)=>{
+                    return (current.get(recordKeyText(record))?.copies ?? []).map((copy)=>{
+                        return verifySignedRecord(copy, params.opKind, params.methods);
+                    });
+                }));
+                for (const op of currentOps)if (op !== null && !heldKeys.has(JSON.stringify([
+                    op.claim.owner,
+                    op.claim.meta.keyID
+                ]))) throw new VaultWriteConflict();
+                const currentEntry = settledValue(entryRead);
+                if (expectedEntry !== undefined && currentEntry?.keyID !== observedEntry?.keyID) throw new VaultWriteConflict();
+                if (!settledValue(keyRead)) throw new VaultWriteConflict();
+                if (expectedEntry !== undefined && (currentEntry?.hlc ?? null) !== expectedEntry.expectedHLC) throw new VaultWriteConflict();
+                return apply(request.records, tx, request.transportContext);
+            });
+        },
+        async listKeyBranches (address) {
+            await assertDomain(bound);
+            return withStoreTransaction(bound.db, async (tx)=>{
+                const rows = await tx.selectFrom('vault_key_branches').selectAll().where('owner_did', '=', address.ownerDID).where('key_id', '=', address.keyID).where('key_version', '=', address.keyVersion).orderBy('branch_id').execute();
+                const ops = await settleAll(rows.map((row)=>verifyRecordOp(row.op_jwt, params.opKind, params.methods)));
+                const result = [];
+                for (const [index, row] of rows.entries()){
+                    const op = ops[index] ?? null;
+                    if (op === null || op.claim.owner !== address.ownerDID || op.claim.id !== address.keyID || op.claim.meta.version !== address.keyVersion || row.branch_id !== `${op.claim.hlc}:${op.opHash}`) throw new VaultRecordRowError({
+                        type: 'vault.key-branch',
+                        owner: row.owner_did,
+                        id: row.record_id
+                    });
+                    result.push({
+                        branchID: row.branch_id,
+                        branchRecordID: row.record_id,
+                        introducingOp: op
+                    });
+                }
+                return result;
+            });
+        },
+        async listWrappingsWithBranch (address) {
+            await assertDomain(bound);
+            return params.store.listWrappings(address);
+        },
+        async rebuildKeyBranches (address) {
+            await assertDomain(bound);
+            const decisions = await adapter.list([
+                'vault.key-branch'
+            ]);
+            const candidates = decisions.flatMap((decision)=>{
+                const record = decision.copies[0];
+                return record !== undefined && record.owner === address.ownerDID ? [
+                    record
+                ] : [];
+            });
+            const ops = await settleAll(candidates.map((record)=>verifySignedRecord(record, params.opKind, params.methods)));
+            const rows = [];
+            for (const [index, record] of candidates.entries()){
+                const op = ops[index] ?? null;
+                if (op === null || op.claim.meta.keyID !== address.keyID) continue;
+                const decoded = decodeVaultRecord(record, op.claim.meta);
+                if (decoded.type !== 'vault.key-branch') continue;
+                rows.push({
+                    owner_did: decoded.owner,
+                    key_id: decoded.meta.keyID,
+                    key_version: decoded.meta.keyVersion,
+                    record_id: decoded.id,
+                    branch_id: decoded.meta.branchID,
+                    op_jwt: decoded.payload.opJWT
+                });
+            }
+            const text = (list)=>{
+                return JSON.stringify(list.map((row)=>[
+                        row.record_id,
+                        row.key_version,
+                        row.branch_id,
+                        row.op_jwt
+                    ]).sort((a, b)=>String(a[0]).localeCompare(String(b[0]))));
+            };
+            return withStoreTransaction(bound.db, async (tx)=>{
+                const held = await tx.selectFrom('vault_key_branches').selectAll().where('owner_did', '=', address.ownerDID).where('key_id', '=', address.keyID).execute();
+                if (text(held) === text(rows)) return false;
+                await tx.deleteFrom('vault_key_branches').where('owner_did', '=', address.ownerDID).where('key_id', '=', address.keyID).execute();
+                // A record ID still projected under another key is taken over, as one upsert per row did.
+                await settleAll(statementChunks(rows, KEY_BRANCH_COLUMNS).map((part)=>{
+                    return upsertKeyBranches(tx, part).execute();
+                }));
+                return true;
+            });
+        },
+        listRevocations: (address)=>vaultRecordPortsFor(adapter).listRevocations(address),
+        listEntryCandidates: (address)=>candidates(address, address.keyVersion, false),
+        listPriorEntryTombstones: (address)=>candidates(address, address.beforeVersion, true)
+    };
+    return api;
+}

package/lib/settle.d.ts

@@ -0,0 +1,12 @@
+export type SettleRelease<Values extends ReadonlyArray<unknown>> = {
+    [Index in keyof Values]?: (value: Values[Index]) => void;
+};
+/**
+ * Waits for every task, then throws the first rejection in task order. Before throwing, runs
+ * `release` on each fulfilled value, so a secret from a fulfilled sibling is still zeroed.
+ */
+export declare function settleAll<Values extends ReadonlyArray<unknown>>(tasks: {
+    [Index in keyof Values]: Promise<Values[Index]>;
+}, release?: SettleRelease<Values>): Promise<Values>;
+/** The value of a settled task, or its rejection thrown. Lets the caller pick the throw order. */
+export declare function settledValue<Value>(result: PromiseSettledResult<Value>): Value;

package/lib/settle.js

@@ -0,0 +1,18 @@
+/**
+ * Waits for every task, then throws the first rejection in task order. Before throwing, runs
+ * `release` on each fulfilled value, so a secret from a fulfilled sibling is still zeroed.
+ */ export async function settleAll(tasks, release) {
+    const settled = await Promise.allSettled(tasks);
+    const failure = settled.find((result)=>result.status === 'rejected');
+    if (failure === undefined) {
+        const values = settled.map((result)=>result.value);
+        return values;
+    }
+    const releases = release;
+    for (const [index, result] of settled.entries())if (result.status === 'fulfilled') releases?.[index]?.(result.value);
+    throw failure.reason;
+}
+/** The value of a settled task, or its rejection thrown. Lets the caller pick the throw order. */ export function settledValue(result) {
+    if (result.status === 'rejected') throw result.reason;
+    return result.value;
+}

package/lib/tables.d.ts

@@ -0,0 +1,42 @@
+import type { Generated } from '@hozon/db';
+import type { FactorDescriptor } from '@kokuin/vault';
+export type VaultKeyTable = {
+    owner_did: string;
+    key_id: string;
+    suite: number;
+    version: number;
+    state: 'active' | 'retired';
+    mode: Generated<'local' | 'replicated'>;
+};
+export type VaultWrappingTable = {
+    owner_did: string;
+    wrapping_id: string;
+    key_id: string;
+    key_version: number;
+    descriptors: Array<FactorDescriptor>;
+    descriptor_digest: string;
+    iv: Uint8Array;
+    wrapped_key: Uint8Array;
+    recipient_did: string | null;
+    provenance: string;
+    mode: Generated<'local' | 'replicated'>;
+};
+export type VaultEntryTable = {
+    owner_did: string;
+    entry_id: string;
+    key_id: string;
+    key_version: number;
+    kind: string;
+    label: string;
+    attributes: Record<string, string>;
+    iv: Uint8Array;
+    ciphertext: Uint8Array;
+    hlc: string;
+    provenance: string;
+    mode: Generated<'local' | 'replicated'>;
+};
+export type VaultStoreTables = {
+    vault_keys: VaultKeyTable;
+    vault_wrappings: VaultWrappingTable;
+    vault_entries: VaultEntryTable;
+};

package/lib/tables.js

@@ -0,0 +1 @@
+export { };

package/lib/types.d.ts

@@ -0,0 +1,74 @@
+import type { EncryptEntryResult, VaultEntryMetadata, WrapResult } from '@kokuin/vault';
+export type KeyAddress = {
+    ownerDID: string;
+    keyID: string;
+};
+export type EntryAddress = {
+    ownerDID: string;
+    entryID: string;
+};
+export type WrappingAddress = {
+    ownerDID: string;
+    wrappingID: string;
+};
+export type KeyRow = KeyAddress & {
+    suite: number;
+    version: number;
+    state: 'active' | 'retired';
+};
+export type EntryMetadata = VaultEntryMetadata;
+export type WrappingRow = KeyAddress & WrapResult & WrappingAddress & {
+    keyVersion: number;
+    recipientDID: string | null;
+    provenance: string;
+};
+export type EntryRow = KeyAddress & EntryAddress & EntryMetadata & EncryptEntryResult & {
+    keyVersion: number;
+    hlc: string;
+    provenance: string;
+};
+export type EntryFilter = KeyAddress & Partial<EntryMetadata>;
+export type UpdateEntryResult = 'updated' | 'absent' | 'superseded';
+export type VaultStoreAPI = {
+    isTransaction: boolean;
+    transaction<Result>(fn: (store: VaultStoreAPI) => Promise<Result>): Promise<Result>;
+    /** Declare the complete key set before authoritative reads. Requires a transaction. */
+    lockKeyRows(addresses: ReadonlyArray<KeyAddress>): Promise<void>;
+    lockKeyRow(address: KeyAddress): Promise<void>;
+    putKey(row: KeyRow): Promise<void>;
+    getKey(address: KeyAddress): Promise<KeyRow | undefined>;
+    listKeys(ownerDID: string): Promise<Array<KeyRow>>;
+    setKeyState(row: KeyAddress & Pick<KeyRow, 'state'>): Promise<void>;
+    setKeyVersion(row: KeyAddress & Pick<KeyRow, 'version'>): Promise<void>;
+    deleteKey(address: KeyAddress): Promise<void>;
+    putWrapping(row: WrappingRow): Promise<void>;
+    /** As `putWrapping` for each row, in batched statements. A later row for one address wins. */
+    putWrappings(rows: ReadonlyArray<WrappingRow>): Promise<void>;
+    getWrapping(address: WrappingAddress): Promise<WrappingRow | undefined>;
+    listWrappings(address: KeyAddress & {
+        keyVersion?: number;
+    }): Promise<Array<WrappingRow>>;
+    deleteWrapping(address: WrappingAddress): Promise<void>;
+    /** As `deleteWrapping` for each address, in batched statements. */
+    deleteWrappings(addresses: ReadonlyArray<WrappingAddress>): Promise<void>;
+    deleteWrappingsBelowVersion(address: KeyAddress & {
+        keyVersion: number;
+    }): Promise<void>;
+    putEntry(row: EntryRow): Promise<void>;
+    /** As `putEntry` for each row, in batched statements. A later row for one address wins. */
+    putEntries(rows: ReadonlyArray<EntryRow>): Promise<void>;
+    /** Stores caller-encrypted bytes. Does nothing if the observed source disappears or changes key. */
+    moveEntry(row: EntryRow): Promise<void>;
+    updateEntryIfPresent(row: EntryRow): Promise<'updated' | 'absent'>;
+    updateEntryIfUnchanged(row: EntryRow & {
+        expectedHLC: string;
+    }): Promise<UpdateEntryResult>;
+    getEntry(address: EntryAddress): Promise<EntryRow | undefined>;
+    getEntryWithProvenance(address: EntryAddress): Promise<EntryRow | undefined>;
+    listEntryOwners(entryID: string): Promise<Array<string>>;
+    listEntries(filter: EntryFilter): Promise<Array<EntryRow>>;
+    deleteEntry(address: EntryAddress): Promise<void>;
+    /** As `deleteEntry` for each address, in batched statements. */
+    deleteEntries(addresses: ReadonlyArray<EntryAddress>): Promise<void>;
+    getMaxEntryHLC(): Promise<string | null>;
+};

package/lib/types.js

@@ -0,0 +1 @@
+export { };

package/package.json

@@ -1,6 +1,48 @@
 {
   "name": "@kokuin/store-vault",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "description": "Hozon-backed local vault storage",
+  "keywords": [
+    "vault",
+    "store"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/TairuFramework/kokuin",
+    "directory": "packages/store-vault"
+  },
+  "license": "MIT",
+  "sideEffects": false,
+  "type": "module",
+  "exports": {
+    ".": "./lib/index.js"
+  },
+  "main": "lib/index.js",
+  "types": "lib/index.d.ts",
+  "files": [
+    "lib/*"
+  ],
+  "dependencies": {
+    "@hozon/adapter": "^0.2.1",
+    "@hozon/db": "^0.5.0",
+    "@kokuin/records": "^0.2.0",
+    "@kokuin/vault": "^0.1.0"
+  },
+  "devDependencies": {
+    "@hozon/node-sqlite": "^0.2.0",
+    "@types/node": "^26.6.5",
+    "kysely": "^0.29.7"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "pnpm run build:clean && pnpm run build:js && pnpm run build:types",
+    "build:clean": "del-cli lib",
+    "build:js": "del-cli 'lib/**/*.js' && swc src -d ./lib --config-file ../../node_modules/@kigu/dev/swc.json --strip-leading-paths",
+    "build:types": "del-cli 'lib/**/*.d.ts' 'lib/**/*.d.ts.map' && tsc --emitDeclarationOnly --skipLibCheck",
+    "test": "pnpm run test:types && pnpm run test:unit",
+    "test:types": "tsc --noEmit --skipLibCheck -p tsconfig.test.json",
+    "test:unit": "vitest run"
+  }
 }