@kubun/store-credential 0.17.3 → 0.18.0

package/lib/api-types.d.ts

@@ -0,0 +1,412 @@
+import type { MethodRegistry } from '@kokuin/token';
+import type { RecordKey, SignedRecord } from '@kubun/records';
+import type { CredentialEntry, CredentialEntryWithProvenance, CredentialFactorDescriptor, CredentialKey, CredentialKeyBranch, CredentialKeyState, CredentialManifestKey, CredentialRecordRow, CredentialRevocation, 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;
+    ownerDID?: 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;
+};
+export type PutCredentialKeyParams = {
+    keyID: string;
+    ownerDID: string;
+    suite: number;
+    version: number;
+    state: CredentialKeyState;
+};
+export type PutCredentialWrappingParams = {
+    wrappingID: string;
+    keyID: string;
+    ownerDID?: string;
+    keyVersion: number;
+    factors: Array<CredentialFactorDescriptor>;
+    iv: Uint8Array;
+    wrappedKey: Uint8Array;
+    recipientDID?: string | null;
+    authority?: WrappingAuthority;
+};
+export type PutCredentialManifestParams = {
+    record: CredentialManifestRecord;
+    token: string;
+    delegationTokens?: Array<string>;
+};
+export type PutCredentialEntryParams = {
+    entryID: string;
+    keyID: string;
+    ownerDID?: string;
+    keyVersion: number;
+    iv: Uint8Array;
+    ciphertext: Uint8Array;
+    hlc: string;
+};
+export type UpdateStoredEntryIfUnchangedParams = PutCredentialEntryParams & {
+    expectedHLC: string;
+};
+/** The address of a device's own grant: which provider, for which owner, on which device. */
+export type CredentialAliasKey = {
+    providerName: string;
+    ownerDID: string;
+    deviceDID: string;
+};
+export type SetDeviceAliasParams = CredentialAliasKey & {
+    entryID: string;
+    /** Owner of the entry; defaults to `ownerDID`. */
+    entryOwnerDID?: string;
+};
+/** Deletes only when the stored `entryID` matches. */
+export type DeleteDeviceAliasIfEntryParams = CredentialAliasKey & {
+    entryID: string;
+};
+export type ListDeviceAliasOwnersParams = {
+    providerName: string;
+    deviceDID: string;
+};
+/**
+ * Per-device grant pointers. Local, like the two-key aliases: each device points at the entry
+ * holding its own grant. Values are stored and compared verbatim, so a caller normalizes.
+ */
+export type CredentialDeviceAliasAPI = {
+    getDeviceAliasEntry(key: CredentialAliasKey): Promise<{
+        entryID: string;
+        entryOwnerDID: string;
+    } | null>;
+    getDeviceAliasEntryID(key: CredentialAliasKey): Promise<string | null>;
+    /** Point `(provider, owner, device)` at `entryID`, replacing any prior target. */
+    setDeviceAliasEntryID(params: SetDeviceAliasParams): Promise<void>;
+    deleteDeviceAliasEntryID(key: CredentialAliasKey): Promise<void>;
+    deleteDeviceAliasIfEntry(params: DeleteDeviceAliasIfEntryParams): Promise<void>;
+    listDeviceAliasOwnersForProvider(params: ListDeviceAliasOwnersParams): Promise<Array<string>>;
+    /** Every device alias of one owner, ordered by provider then device. */
+    listDeviceAliasesForOwner(ownerDID: string): Promise<Array<CredentialAliasKey & {
+        entryID: 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.
+ *
+ * Replicated writes use signed records; local GraphQL writes use these row verbs.
+ * Owner-qualified arguments address one projection. An omitted owner is accepted
+ * only when the stored ID has one owner; ambiguous IDs fail closed. Legacy local
+ * writes without a key row use the empty owner namespace.
+ */
+export type CredentialStoreAPI = CredentialDeviceAliasAPI & {
+    /** Whether this store is bound to a caller-owned database transaction. */
+    readonly isTransaction?: boolean;
+    /**
+     * 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>;
+    /**
+     * Serialize writers of one key's version, wrappings and entries.
+     * Call first inside a transaction, before reading those rows. The lock lasts
+     * until that transaction commits or rolls back, even if the key row is absent.
+     * Call `lockKeyRows` instead when a transaction can touch more than one key.
+     */
+    lockKeyRow(keyID: string): Promise<void>;
+    /** Acquire a complete key set before authoritative reads; Postgres orders by advisory ID. */
+    lockKeyRows(keyIDs: ReadonlyArray<string>): Promise<void>;
+    putKey(params: PutCredentialKeyParams): Promise<void>;
+    getKey(keyID: string, ownerDID?: string): Promise<CredentialKey | undefined>;
+    listKeys(ownerDID: string): Promise<Array<CredentialKey>>;
+    setKeyState(keyID: string, state: CredentialKeyState, ownerDID?: string): Promise<void>;
+    /** Bump a key to a new version. Wrappings and entries at earlier versions stay. */
+    setKeyVersion(keyID: string, version: number, ownerDID?: string): Promise<void>;
+    deleteKey(keyID: string, ownerDID?: string): Promise<void>;
+    listKeyBranches(keyID: string, keyVersion: number, ownerDID?: string): Promise<Array<CredentialKeyBranch>>;
+    /**
+     * `authority`, when present, upserts the wrapping's grantor-authority envelope
+     * in the SAME transaction as the wrapping row, 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): Promise<void>;
+    getWrapping(wrappingID: string, ownerDID?: string): Promise<CredentialWrapping | undefined>;
+    /** Every wrapping for a key, or only those at one version. */
+    listWrappings(keyID: string, keyVersion?: number, ownerDID?: string): Promise<Array<CredentialWrapping>>;
+    /**
+     * As {@link listWrappings}, each row carrying the branch of its replicated record.
+     * The fork-aware read path
+     * needs the label to resolve which content-key branch a device opens.
+     */
+    listWrappingsWithBranch(keyID: string, keyVersion?: number, ownerDID?: string): Promise<Array<CredentialWrappingWithBranch>>;
+    deleteWrapping(wrappingID: string, ownerDID?: string): Promise<void>;
+    /**
+     * Drop every wrapping for a key below `keyVersion` — what a rotation leaves
+     * behind. Replicated deletion uses record tombstones through the record adapter.
+     */
+    deleteWrappingsBelowVersion(keyID: string, keyVersion: number, ownerDID?: string): Promise<void>;
+    putEntry(params: PutCredentialEntryParams): Promise<void>;
+    /**
+     * Explicitly change an entry's key association. Callers must authorize both
+     * source and target keys before invoking this capability.
+     */
+    moveEntry(params: PutCredentialEntryParams): Promise<void>;
+    /**
+     * Write over an entry's ciphertext ONLY if the row already exists under the
+     * same key — never inserts, never moves it. Returns 'absent' when nothing was updated.
+     */
+    updateEntryIfPresent(params: PutCredentialEntryParams): Promise<'updated' | 'absent'>;
+    /**
+     * As {@link updateEntryIfPresent}, and also conditional on the entry row still
+     * carrying `expectedHLC`, the stamp its writer read it at. The check and the
+     * write are one atomic section, so a write that landed since that read (a new
+     * consent, say) is never overwritten: it reports `'superseded'` and touches
+     * nothing.
+     */
+    updateEntryIfUnchanged(params: UpdateStoredEntryIfUnchangedParams): Promise<'updated' | 'absent' | 'superseded'>;
+    getEntry(entryID: string, ownerDID?: string): Promise<CredentialEntry | undefined>;
+    listEntryOwners(entryID: string): Promise<Array<string>>;
+    getEntryWithProvenance(entryID: string, ownerDID?: string): Promise<CredentialEntryWithProvenance | undefined>;
+    listEntries(keyID: string, ownerDID?: 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, ownerDID?: string): Promise<void>;
+    /** 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, ownerDID?: 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(params: PutCredentialManifestParams): 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;
+        ownerDID?: 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;
+        ownerDID?: 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, ownerDID?: string): Promise<{
+        delegationTokens: Array<string>;
+        refreshSeq: number;
+        revision: number;
+    } | undefined>;
+    /**
+     * The stored row of one replicated record, tombstone included, as the table holds it.
+     * `credentialRecordAdapter` reads records through this; nothing here decodes the row.
+     */
+    getRecordRow(type: string, id: string): Promise<CredentialRecordRow | undefined>;
+    getRecordRows(key: RecordKey): Promise<Array<CredentialRecordRow>>;
+    /** `getRecordRows` of each key, keyed by `recordKeyText`; a key without rows is absent. */
+    getRecordRowsForKeys(keys: ReadonlyArray<RecordKey>): Promise<Map<string, Array<CredentialRecordRow>>>;
+    deleteRecordCopy(key: RecordKey, opHash: string): Promise<void>;
+    /**
+     * The stored rows of every record of the given types. Their order is the adapter's
+     * collation, which differs between SQLite and Postgres, so a caller that needs an order
+     * sorts them itself.
+     */
+    listRecordRows(types: ReadonlyArray<string>): Promise<Array<CredentialRecordRow>>;
+    /**
+     * Store a signed record as the current op of its `(type, id)` with its indexed row, in
+     * one transaction. See `putCredentialRecord` for what it checks and throws.
+     */
+    putRecord(record: SignedRecord, methods?: MethodRegistry): Promise<void>;
+    /** All authenticated entry candidates, including losing branch operations. */
+    listEntryCandidates(keyID: string, keyVersion: number, ownerDID?: string): Promise<Array<SignedRecord>>;
+    /** Earlier signed tombstones that must participate in fork repair entry ordering. */
+    listPriorEntryTombstones(keyID: string, beforeVersion: number, ownerDID?: string): Promise<Array<SignedRecord>>;
+    /** Called after record authorization, including when the candidate loses the merge. */
+    retainEntryCandidate(record: SignedRecord, methods?: MethodRegistry): Promise<void>;
+    /** The recipients revoked from a key, ordered by recipient. */
+    listRevocations(keyID: string, ownerDID?: string): Promise<Array<CredentialRevocation>>;
+};

package/lib/api-types.js

@@ -0,0 +1,14 @@
+/**
+ * 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.
+ *
+ * Replicated writes use signed records; local GraphQL writes use these row verbs.
+ * Owner-qualified arguments address one projection. An omitted owner is accepted
+ * only when the stored ID has one owner; ambiguous IDs fail closed. Legacy local
+ * writes without a key row use the empty owner namespace.
+ */ export { };