@kubun/store-credential 0.17.3 → 0.18.0

package/lib/api.d.ts

@@ -1,436 +1,12 @@
 import type { Adapter } from '@kubun/db-adapter';
-import { type Kysely } from 'kysely';
-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.
- *
- * `opJWT` is opaque here — this package neither signs nor verifies, the same way
- * it neither encrypts nor decrypts. `@kubun/credential` mints these and is the
- * only thing that can read one.
- */
-export type CredentialOpInput = {
-    keyID: string;
-    authorDID: string;
-    hlc: string;
-    opJWT: string;
-    opHash: string;
-    /**
-     * The content-key branch this op joins — `${hlc}:${opHash}` of the branch's
-     * introducing key-op. Empty when the op is minted outside a rotation/create
-     * and so does not resolve the branch it belongs to.
-     */
-    branchID: string;
-};
-/** A tombstone for one subject of a multi-row delete, which names its own. */
-export type CredentialTombstoneInput = CredentialOpInput & {
-    subjectID: string;
-};
-export type PutCredentialKeyParams = {
-    keyID: string;
-    ownerDID: string;
-    suite: number;
-    version: number;
-    state: CredentialKeyState;
-};
-export type PutCredentialWrappingParams = {
-    wrappingID: string;
-    keyID: string;
-    keyVersion: number;
-    factors: Array<CredentialFactorDescriptor>;
-    iv: Uint8Array;
-    wrappedKey: Uint8Array;
-    recipientDID?: string | null;
-};
-export type PutCredentialEntryParams = {
-    entryID: string;
-    keyID: string;
-    keyVersion: number;
-    iv: Uint8Array;
-    ciphertext: Uint8Array;
-    hlc: string;
-};
-export type HeldCredentialSubject = {
-    subjectKind: CredentialOpSubjectKind;
-    subjectID: string;
-    opHash: string;
-};
-/**
- * Persistence for credential keys, wrappings and entries.
- *
- * Storage only: nothing here wraps, unwraps, encrypts or decrypts, and nothing
- * here interprets a ciphertext. `ciphertext` and `wrapped_key` are opaque byte
- * strings that come back exactly as they went in — not parsed as JSON, not
- * decoded as UTF-8, not validated in any way. A caller owning the crypto is what
- * lets the suite change without a migration.
- *
- * A deletion is NOT the absence of a row. It is a tombstone in
- * `kubun_credential_ops`, and the row is gone from its own table — so asking
- * whether a wrapping exists means reading two tables, not one. Absence alone
- * cannot travel over a lane that only adds: a peer holding the deleted row would
- * ship it back and this device would store it again. So a `put` carrying an op no
- * newer than the tombstone writes NOTHING, silently — that is the resend.
- *
- * The op is REQUIRED, and `null` is how a writer says it has none rather than
- * how it says nothing. A row written with `null` is stored but speaks for
- * itself, invisible to the sync lane; making the parameter mandatory is what
- * stops a write path added later from being silently unsigned. Only the GraphQL
- * 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>>;
-    setKeyState(keyID: string, state: CredentialKeyState, op: CredentialOpInput | null): Promise<void>;
-    /** Bump a key to a new version. Wrappings and entries at earlier versions stay. */
-    setKeyVersion(keyID: string, version: number, op: CredentialOpInput | null): Promise<void>;
-    deleteKey(keyID: string, tombstone: CredentialOpInput | null): Promise<void>;
-    recordKeyBranch(params: {
-        keyID: string;
-        keyVersion: number;
-        authorDID: string;
-        hlc: string;
-        opJWT: string;
-        opHash: string;
-        branchID: string;
-    }): Promise<void>;
-    listKeyBranches(keyID: string, keyVersion: number): Promise<Array<CredentialKeyBranch>>;
-    /**
-     * `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>>;
-    /**
-     * As {@link listWrappings}, each row carrying its op's `branch_id`. The
-     * fork-aware read path needs the label to resolve which content-key branch a
-     * device opens; every other caller reads none, so the join stays off the
-     * common path.
-     */
-    listWrappingsWithBranch(keyID: string, keyVersion?: number): Promise<Array<CredentialWrappingWithBranch>>;
-    deleteWrapping(wrappingID: string, tombstone: CredentialOpInput | null): Promise<void>;
-    /**
-     * Drop every wrapping for a key below `keyVersion` — what a rotation leaves
-     * behind. The tombstones name their own subjects, because the caller decides
-     * which rows it is accounting for and the delete predicate spans many.
-     */
-    deleteWrappingsBelowVersion(keyID: string, keyVersion: number, tombstones: Array<CredentialTombstoneInput> | null): Promise<void>;
-    putEntry(params: PutCredentialEntryParams, op: CredentialOpInput | null): Promise<void>;
-    /**
-     * Explicitly change an entry's key association. Callers must authorize both
-     * source and target keys before invoking this capability.
-     */
-    moveEntry(params: PutCredentialEntryParams, op: CredentialOpInput | null): Promise<void>;
-    /**
-     * Write over an entry's ciphertext ONLY if the row already exists under the
-     * same key — never inserts, never moves it. Op-first like putEntry: the op is
-     * written under the op-conflict lock, then the row; if no matching row is
-     * present (concurrently deleted, or re-keyed away) the op is rolled back, so a
-     * refresh writeback can neither revive a concurrently-deleted entry nor leave
-     * an op stranded without its row. Returns 'absent' when nothing was updated.
-     */
-    updateEntryIfPresent(params: PutCredentialEntryParams, op: CredentialOpInput | null): Promise<'updated' | 'absent'>;
-    getEntry(entryID: string): Promise<CredentialEntry | undefined>;
-    getEntryWithProvenance(entryID: string): Promise<CredentialEntryWithProvenance | undefined>;
-    listEntries(keyID: string): Promise<Array<CredentialEntry>>;
-    /**
-     * Greatest stored entry HLC, or `null` when there are none. Credential writes
-     * advance the device clock but leave no row in the graph mutation log, so this
-     * is the only trace they leave for a restart floor to read.
-     */
-    getMaxEntryHLC(): Promise<string | null>;
-    deleteEntry(entryID: string, tombstone: CredentialOpInput | null): Promise<void>;
-    /** The op a subject's current state came from, tombstone included. */
-    getOp(subjectKind: CredentialOpSubjectKind, subjectID: string): Promise<CredentialOp | undefined>;
-    /**
-     * Ops in stamp order — every one, or one key's. This is the merkle lane's leaf
-     * scan, which is why the ops of all three subject kinds share a table.
-     */
-    listOps(keyID?: string): Promise<Array<CredentialOp>>;
-    /**
-     * The leaf scan scoped to what a requesting peer may hold.
-     *
-     * The document lane serves a tree scoped by read-ACL, but a credential is not
-     * readable by scope: a group co-member holds no wrapping under someone else's
-     * key, so serving them its rows ships ciphertext they can never open and reveals
-     * the key exists. The predicate is recipient-addressed instead. A key's row and
-     * its entry ops travel to any recipient of the key — a peer holding a wrapping
-     * under it. A wrapping's op travels only to the DID it names, so a recipient
-     * never receives a co-recipient's wrapping. Recipient match folds both sides
-     * with `normalizeDID`, because `recipient_did` is stored un-normalized.
-     */
-    listOpsForRequester(requesterDID: string, keyID?: string): Promise<Array<CredentialOp>>;
-    /**
-     * The live (non-tombstoned) subject ids this device holds — keys, wrappings and
-     * entries alike. What a reconcile caller advertises as `held`: the server reads
-     * it to skip rows the caller already has and to route a tombstone for a held id
-     * that is now revoked.
-     */
-    listHeldSubjects(): Promise<Array<HeldCredentialSubject>>;
-    /**
-     * The entry id currently pointed to by an opaque `(namespace, key)`, or
-     * `null` when unset. Neither argument is interpreted — a caller normalizes
-     * whatever it means by "key" before calling.
-     */
-    getAliasEntryID(namespace: string, key: string): Promise<string | null>;
-    /** Point `(namespace, key)` at `entryID`, replacing any prior target. */
-    setAliasEntryID(namespace: string, key: string, entryID: string): Promise<void>;
-    /**
-     * Bind `(namespace, aliasKey)` to `entryID` only if the alias slot is free and
-     * the entry exists — unlike {@link setAliasEntryID}, this never overwrites an
-     * existing alias and never binds a nonexistent entry. Classifies the outcome
-     * instead of throwing, since both unique constraints are expected outcomes a
-     * caller branches on, not exceptional ones.
-     */
-    bindAliasIfAbsent(namespace: string, aliasKey: string, entryID: string): Promise<'inserted' | 'entry-missing' | {
-        conflict: 'alias';
-        existing: string;
-    } | {
-        conflict: 'entry';
-    }>;
-    /** Clear an alias. A no-op, not an error, when none is set. */
-    deleteAliasEntryID(namespace: string, key: string): Promise<void>;
-    /**
-     * Clear an alias only while it still points at `entryID`. A concurrent rebind
-     * that repaired the pointer onto a fresh entry in the gap after the old entry
-     * was deleted is left intact; a no-op when the pointer already moved or is unset.
-     */
-    deleteAliasIfEntry(namespace: string, key: string, entryID: 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>;
-    /**
-     * Abandon ALL outstanding provisioning attempts for one (owner, grantor)
-     * scope. Deletes every attempt row for the pair, never touches the
-     * expectation floor. The recovery escape hatch when the attempt id is lost.
-     *
-     * Exclusive-recovery contract: this also clears any OTHER live coordinator's
-     * attempt on the same scope (whose later `recordProvisioningAttempt` would
-     * then hit the phantom-attempt guard and not raise the floor). Callers must
-     * ensure no other live attempt exists for the scope before calling. When the
-     * id is known, prefer `abandonProvisioningAttempt`, which is safe under
-     * concurrency.
-     */
-    abandonProvisioningAttempts(params: {
-        ownerDID: string;
-        grantorDID: 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>>;
-    /**
-     * Refresh a controller-owned key's `credential/administer` delegation chain,
-     * gated strictly-greater on `refreshSeq` (stale/replayed is a silent no-op,
-     * same shape as {@link CredentialStoreAPI.putWrappingAuthority}). Handles
-     * both the absent-row insert and the monotone race. Returns whether a row
-     * was inserted or updated.
-     */
-    refreshKeyOwnerDelegation(params: {
-        keyID: string;
-        delegationTokens: Array<string>;
-        refreshSeq: number;
-    }): Promise<boolean>;
-    /**
-     * Compare-and-swap a key-owner delegation chain, guarded on the `revision`
-     * the caller read. Replaces the row only when its CURRENT `revision` still
-     * equals `expectedRevision`, so a writer that read an invalid-present chain
-     * and revalidated it can install a replacement without racing another such
-     * writer or a concurrent refresh. The guard is `revision`, NOT `refreshSeq`:
-     * two distinct valid chains can share a `refreshSeq` (min-exp ms), so guarding
-     * on the seq has an ABA hole. Unlike {@link refreshKeyOwnerDelegation} this
-     * never inserts and is not monotone — it is the escape hatch for the
-     * invalid-present case, where the incoming chain's `refreshSeq` may be lower.
-     * Absent row is a no-op false, same as a revision mismatch. A successful
-     * write bumps `revision`.
-     */
-    replaceKeyOwnerDelegationIfUnchanged(params: {
-        keyID: string;
-        expectedRevision: number;
-        delegationTokens: Array<string>;
-        refreshSeq: number;
-    }): Promise<boolean>;
-    /** The stored delegation chain, its `refreshSeq`, and its `revision`, or `undefined` when unset. */
-    getKeyOwnerDelegation(keyID: string): Promise<{
-        delegationTokens: Array<string>;
-        refreshSeq: number;
-        revision: number;
-    } | undefined>;
-};
+import type { Kysely } from 'kysely';
+import type { CredentialStoreAPI } from './api-types.js';
+import type { CredentialTables } from './tables.js';
+export type * from './api-types.js';
 /**
  * `refreshSeq` sentinel for a delegation chain that has no future refresh —
  * larger than any real ms timestamp, so a bounded refresh can never overtake
  * it. Consumed by `@kubun/plugin-p2p`.
  */
 export declare const UNBOUNDED_REFRESH_SEQ = 8640000000000000;
-export declare function createCredentialStore(db: Kysely<CredentialTables>, adapter: Adapter): CredentialStoreAPI;
+export declare function createCredentialStore(db: Kysely<CredentialTables>, adapter: Adapter, advisoryIDForKey?: (keyID: string) => bigint | Promise<bigint>): CredentialStoreAPI;