@kubun/credential 0.13.0

package/lib/errors.js

@@ -0,0 +1,248 @@
+/**
+ * Failures a caller acts on differently.
+ *
+ * The distinctions are not cosmetic. "This device cannot supply the factor" is a
+ * prompt-the-user or use-another-device outcome; "the descriptors were tampered
+ * with" is a security event; "wrong secret" is a retry. Collapsing them into one
+ * decrypt error is what makes a tampered wrapping indistinguishable from a
+ * mistyped PIN.
+ *
+ * `code` is required rather than defaulted: a subclass that inherited a generic
+ * code would compile, ship, and reach a client as an untyped failure, which is
+ * the one outcome this hierarchy exists to prevent.
+ */ export class CredentialError extends Error {
+    #code;
+    constructor(message, options){
+        super(message, options);
+        this.name = 'CredentialError';
+        this.#code = options.code;
+    }
+    get code() {
+        return this.#code;
+    }
+}
+/** A wrapping needs a factor kind this device cannot supply. */ export class NoAvailableFactor extends CredentialError {
+    #kind;
+    constructor(kind){
+        super(`No available credential factor of kind "${kind}" on this device`, {
+            code: 'CREDENTIAL_FACTOR_UNAVAILABLE'
+        });
+        this.name = 'NoAvailableFactor';
+        this.#kind = kind;
+    }
+    get kind() {
+        return this.#kind;
+    }
+}
+/**
+ * A factor list a wrapping may not be built from.
+ *
+ * Raised at creation rather than at first unwrap: an unopenable or ambiguous
+ * wrapping that only fails on read is a key nobody notices is broken until they
+ * need it.
+ */ export class InvalidCredentialFactors extends CredentialError {
+    constructor(reason){
+        super(`Invalid credential factor list: ${reason}`, {
+            code: 'CREDENTIAL_FACTORS_INVALID'
+        });
+        this.name = 'InvalidCredentialFactors';
+    }
+}
+/** A key names a ciphersuite this build does not implement. */ export class UnsupportedCredentialSuite extends CredentialError {
+    #suite;
+    constructor(suite){
+        super(`Unsupported credential suite ${suite}`, {
+            code: 'CREDENTIAL_SUITE_UNSUPPORTED'
+        });
+        this.name = 'UnsupportedCredentialSuite';
+        this.#suite = suite;
+    }
+    get suite() {
+        return this.#suite;
+    }
+}
+/**
+ * A wrapping did not authenticate, and no user-supplied secret was involved.
+ *
+ * Raised for a wrapping whose factors are all `did`, where nothing the user
+ * typed could have been wrong. The causes left are an edited descriptor list,
+ * corrupted ciphertext, a wrapping copied onto another row — **and a wrapping
+ * addressed to someone else**. X25519 agreement never fails: a foreign recipient
+ * recovers different bytes rather than erroring, so the tag fails identically. A
+ * wrapping this device is not addressed to normally never reaches an unwrap at
+ * all, because `satisfiableFactors` filters it out first.
+ */ export class CredentialTampered extends CredentialError {
+    constructor(message, options){
+        super(message, {
+            ...options,
+            code: 'CREDENTIAL_TAMPERED'
+        });
+        this.name = 'CredentialTampered';
+    }
+}
+/** An entry belongs to a branch superseded by the key's resolved winner. */ export class CredentialSupersededBranch extends CredentialError {
+    #entryID;
+    #entryBranchID;
+    #winnerBranchID;
+    constructor(entryID, entryBranchID, winnerBranchID){
+        super(`Credential entry ${entryID} belongs to superseded branch ${entryBranchID}; winner is ${winnerBranchID}`, {
+            code: 'CREDENTIAL_SUPERSEDED_BRANCH'
+        });
+        this.name = 'CredentialSupersededBranch';
+        this.#entryID = entryID;
+        this.#entryBranchID = entryBranchID;
+        this.#winnerBranchID = winnerBranchID;
+    }
+    get entryID() {
+        return this.#entryID;
+    }
+    get entryBranchID() {
+        return this.#entryBranchID;
+    }
+    get winnerBranchID() {
+        return this.#winnerBranchID;
+    }
+}
+/**
+ * A wrapping carrying a user-supplied factor did not authenticate.
+ *
+ * Attribution to a wrong secret is policy, not a cryptographic fact: one tag
+ * failure is all that is observable, and a tampered descriptor produces the same
+ * one. This is the retry path; the `pin` throttle bounds repeated attempts.
+ */ export class CredentialSecretRejected extends CredentialError {
+    #kinds;
+    constructor(kinds, options){
+        const keyID = options?.keyID;
+        super(`Credential ${kinds.join(' and ')} rejected${keyID == null ? '' : ` for key ${keyID}`}. If the secret is known to be correct, the wrapping's factor descriptors may have been altered — the two are indistinguishable at this point.`, {
+            ...options,
+            code: options?.code ?? 'CREDENTIAL_SECRET_REJECTED'
+        });
+        this.name = 'CredentialSecretRejected';
+        this.#kinds = kinds;
+    }
+    /** The user-supplied factor kinds in the wrapping, any of which could be wrong. */ get kinds() {
+        return this.#kinds;
+    }
+}
+/**
+ * A PIN attempt was wrong, or refused because too many already were.
+ *
+ * Raised by the manager rather than the suite: the counter is per-key and the
+ * suite holds none. A refusal is issued before the KDF runs, so a throttled
+ * attempt costs the attacker time and the defender nothing.
+ */ export class CredentialPinRejected extends CredentialSecretRejected {
+    #attemptsRemaining;
+    #retryAfter;
+    constructor(keyID, options){
+        super([
+            'pin'
+        ], {
+            cause: options.cause,
+            keyID,
+            code: 'CREDENTIAL_PIN_REJECTED'
+        });
+        this.name = 'CredentialPinRejected';
+        this.#attemptsRemaining = options.attemptsRemaining;
+        this.#retryAfter = options.retryAfter;
+    }
+    /** Attempts left before a delay begins. */ get attemptsRemaining() {
+        return this.#attemptsRemaining;
+    }
+    /** Milliseconds until another attempt is accepted. Zero means now. */ get retryAfter() {
+        return this.#retryAfter;
+    }
+}
+/**
+ * This identity holds no authority to do that to that key.
+ *
+ * Named rather than collapsed into {@link CredentialNotFound}, which is what a
+ * verb with no ownership check reports once it goes looking for a wrapping it
+ * was never entitled to touch. "There is no such key here" and "that key is not
+ * yours to administer" want opposite things from a caller, and only one of them
+ * is worth retrying on another device.
+ */ export class CredentialNotAuthorized extends CredentialError {
+    #authorization;
+    constructor(authorization, keyID){
+        super(`Not authorized to ${authorization} credential key ${keyID}`, {
+            code: 'CREDENTIAL_NOT_AUTHORIZED'
+        });
+        this.name = 'CredentialNotAuthorized';
+        this.#authorization = authorization;
+    }
+    get authorization() {
+        return this.#authorization;
+    }
+}
+/** No key, wrapping or entry under that id. */ export class CredentialNotFound extends CredentialError {
+    constructor(what, id){
+        super(`${what} not found: ${id}`, {
+            code: 'CREDENTIAL_NOT_FOUND'
+        });
+        this.name = 'CredentialNotFound';
+    }
+}
+/**
+ * More than one wrapping on a key is addressed to this device.
+ *
+ * Thrown rather than resolved by picking: re-wrapping one of them would leave
+ * the other un-gated and look like success.
+ */ export class AmbiguousCredentialWrapping extends CredentialError {
+    constructor(keyID, count){
+        super(`Credential key ${keyID} has ${count} wrappings addressed to this device; which one to re-wrap is ambiguous`, {
+            code: 'CREDENTIAL_WRAPPING_AMBIGUOUS'
+        });
+        this.name = 'AmbiguousCredentialWrapping';
+    }
+}
+/**
+ * The key is closed, and a factor this device can supply would open it.
+ *
+ * Distinct from {@link CredentialUnopenable} because the two need opposite
+ * responses: this one is a prompt, that one is "use another device". Collapsing
+ * them makes the UI ask for a PIN that will never work.
+ */ export class CredentialKeyLocked extends CredentialError {
+    #keyID;
+    constructor(keyID, kinds){
+        super(`Credential key ${keyID} is locked; unlock it with: ${kinds.join(', ')}`, {
+            code: 'CREDENTIAL_KEY_LOCKED'
+        });
+        this.name = 'CredentialKeyLocked';
+        this.#keyID = keyID;
+    }
+    get keyID() {
+        return this.#keyID;
+    }
+}
+/**
+ * An entry was written under a key version the key has moved past.
+ *
+ * Rotation re-encrypts every entry, so this is a rotation that crashed partway.
+ * Loud by design: falling back to the older version would read a value the
+ * rotation was meant to retire, and silently.
+ */ export class CredentialKeyVersionMismatch extends CredentialError {
+    constructor(entryID, entryVersion, keyVersion){
+        super(`Credential entry ${entryID} is at key version ${entryVersion} but its key is at ${keyVersion}: a rotation did not complete`, {
+            code: 'CREDENTIAL_KEY_VERSION_MISMATCH'
+        });
+        this.name = 'CredentialKeyVersionMismatch';
+    }
+}
+/**
+ * Every wrapping for the key was tried and none opened.
+ *
+ * Reported rather than skipped: a key whose only wrapping uses an unimplemented
+ * suite, or whose factors this device lacks, is a state the caller must be able
+ * to show. Silently returning "no entries" would read as an empty vault.
+ */ export class CredentialUnopenable extends CredentialError {
+    #keyID;
+    constructor(keyID, reason){
+        super(`Credential key ${keyID} cannot be opened on this device: ${reason}`, {
+            code: 'CREDENTIAL_UNOPENABLE'
+        });
+        this.name = 'CredentialUnopenable';
+        this.#keyID = keyID;
+    }
+    get keyID() {
+        return this.#keyID;
+    }
+}

package/lib/index.d.ts

@@ -0,0 +1,19 @@
+export type { CredentialAuthority, CredentialAuthorityParams, CredentialAuthorization, } from './authority.js';
+export { createDeviceAuthority } from './authority.js';
+export type { BuildEntryParams, BuildKeyParams, BuiltEntry, BuiltKey, BuiltWrapping, CredentialKeyMaterial, } from './builder.js';
+export { buildCredentialEntry, buildCredentialKey } from './builder.js';
+export type { CredentialEntryDigestInput, CredentialKeyDigestInput, CredentialWrappingDigestInput, } from './digest.js';
+export { credentialEntriesDigest, credentialEntryDigest, credentialKeyDigest, credentialWrappingDigest, digestParts, } from './digest.js';
+export type { CredentialErrorCode, CredentialErrorOptions } from './errors.js';
+export { AmbiguousCredentialWrapping, CredentialError, CredentialKeyLocked, CredentialKeyVersionMismatch, CredentialNotAuthorized, CredentialNotFound, CredentialPinRejected, CredentialSecretRejected, CredentialSupersededBranch, CredentialTampered, CredentialUnopenable, InvalidCredentialFactors, NoAvailableFactor, UnsupportedCredentialSuite, } from './errors.js';
+export type { CreateCredentialManagerParams, CreateKeyParams, CredentialGrantResult, CredentialKeyStatus, CredentialManager, CredentialUnopenableReason, FactorChangeParams, GrantKeyParams, ReKeyEntryParams, RotateKeyParams, } from './manager.js';
+export { createCredentialManager } from './manager.js';
+export type { CredentialOpClaim, CredentialOpSigner, CredentialOpSubject, CredentialPutSubject, CredentialRowSubject, VerifiedCredentialOp, } from './op.js';
+export { compareBranchIDs, createCredentialOpSigner, credentialOpMatchesPut, credentialOpMatchesRow, credentialPutDigest, credentialRowDigest, selectWinningBranch, verifyCredentialOp, } from './op.js';
+export type { PinThrottle, PinThrottleParams } from './pin-throttle.js';
+export { createPinThrottle, DEFAULT_BASE_DELAY, DEFAULT_FREE_ATTEMPTS, DEFAULT_MAX_DELAY, } from './pin-throttle.js';
+export type { CredentialEntryProvenance } from './provenance.js';
+export { entryProvenanceFields } from './provenance.js';
+export type { Argon2Cost, CredentialSuite, FactorInput, FactorInputs, SecretFactorKind, } from './suite.js';
+export { DEFAULT_ARGON2_COST, getSuite, isSupportedSuite, SUITE_KUBUN_CRED_1 } from './suite.js';
+export { CREDENTIAL_ADMINISTER_ACTION, credentialUserResource } from './vocabulary.js';

package/lib/index.js

@@ -0,0 +1,10 @@
+export { createDeviceAuthority } from './authority.js';
+export { buildCredentialEntry, buildCredentialKey } from './builder.js';
+export { credentialEntriesDigest, credentialEntryDigest, credentialKeyDigest, credentialWrappingDigest, digestParts } from './digest.js';
+export { AmbiguousCredentialWrapping, CredentialError, CredentialKeyLocked, CredentialKeyVersionMismatch, CredentialNotAuthorized, CredentialNotFound, CredentialPinRejected, CredentialSecretRejected, CredentialSupersededBranch, CredentialTampered, CredentialUnopenable, InvalidCredentialFactors, NoAvailableFactor, UnsupportedCredentialSuite } from './errors.js';
+export { createCredentialManager } from './manager.js';
+export { compareBranchIDs, createCredentialOpSigner, credentialOpMatchesPut, credentialOpMatchesRow, credentialPutDigest, credentialRowDigest, selectWinningBranch, verifyCredentialOp } from './op.js';
+export { createPinThrottle, DEFAULT_BASE_DELAY, DEFAULT_FREE_ATTEMPTS, DEFAULT_MAX_DELAY } from './pin-throttle.js';
+export { entryProvenanceFields } from './provenance.js';
+export { DEFAULT_ARGON2_COST, getSuite, isSupportedSuite, SUITE_KUBUN_CRED_1 } from './suite.js';
+export { CREDENTIAL_ADMINISTER_ACTION, credentialUserResource } from './vocabulary.js';

package/lib/key-cache.d.ts

@@ -0,0 +1,34 @@
+/** 15 minutes. Long enough for a working session, short enough to matter. */
+export declare const DEFAULT_UNLOCK_TTL: number;
+export type KeyCacheParams = {
+    /**
+     * How long an unlocked key stays in memory. Eviction is lazy — checked on
+     * read — because a timer would keep the host process alive and make every
+     * test wait on a clock it does not control.
+     */
+    ttl?: number;
+    /** Injectable so a TTL test does not sleep. */
+    now?: () => number;
+};
+/**
+ * The unlocked content keys, and the only place lock state exists.
+ *
+ * It is deliberately not a column. Locked, unlocked and unopenable are derived
+ * from what is here plus which wrappings exist; a persisted `unlocked` would be
+ * a belief that survives a restart it should not.
+ */
+export type KeyCache = {
+    /**
+     * The cached key and the branch it resolved to, or null if absent, expired,
+     * or from a superseded version. A cache hit still surfaces the branch so a
+     * post-fork write joins the same branch the first open resolved.
+     */
+    get(keyID: string, keyVersion: number): {
+        contentKey: Uint8Array;
+        branchID: string;
+    } | null;
+    set(keyID: string, contentKey: Uint8Array, keyVersion: number, branchID: string): void;
+    evict(keyID: string): void;
+    evictAll(): void;
+};
+export declare function createKeyCache(params?: KeyCacheParams): KeyCache;

package/lib/key-cache.js

@@ -0,0 +1,55 @@
+/** 15 minutes. Long enough for a working session, short enough to matter. */ export const DEFAULT_UNLOCK_TTL = 15 * 60 * 1000;
+export function createKeyCache(params = {}) {
+    const ttl = params.ttl ?? DEFAULT_UNLOCK_TTL;
+    const now = params.now ?? Date.now;
+    const entries = new Map();
+    /**
+   * Overwrite the key material before dropping the entry.
+   *
+   * Dropping the entry alone leaves the bytes wherever they are until a
+   * collector reaches them. Zeroing is the part that can be guaranteed;
+   * JavaScript cannot promise no interpreter-level copy survives, and the design
+   * spec records that limit rather than implying hygiene it cannot deliver.
+   */ function evict(keyID) {
+        const cached = entries.get(keyID);
+        if (cached != null) {
+            cached.contentKey.fill(0);
+            entries.delete(keyID);
+        }
+    }
+    return {
+        get (keyID, keyVersion) {
+            const cached = entries.get(keyID);
+            if (cached == null) {
+                return null;
+            }
+            // A rotation invalidates the cache as surely as time does: serving the
+            // pre-rotation key would decrypt entries the rotation was retiring.
+            if (now() - cached.unlockedAt >= ttl || cached.keyVersion !== keyVersion) {
+                evict(keyID);
+                return null;
+            }
+            return {
+                contentKey: cached.contentKey,
+                branchID: cached.branchID
+            };
+        },
+        set (keyID, contentKey, keyVersion, branchID) {
+            evict(keyID);
+            entries.set(keyID, {
+                contentKey,
+                keyVersion,
+                branchID,
+                unlockedAt: now()
+            });
+        },
+        evict,
+        evictAll () {
+            for (const keyID of [
+                ...entries.keys()
+            ]){
+                evict(keyID);
+            }
+        }
+    };
+}

package/lib/manager.d.ts

@@ -0,0 +1,280 @@
+import { type MethodRegistry, type SigningIdentity } from '@kokuin/token';
+import { HLC } from '@kubun/hlc';
+import type { CredentialStoreAPI } from '@kubun/store-credential';
+import type { Runtime } from '@sozai/runtime';
+import { type CredentialAuthority } from './authority.js';
+import { type PinThrottleParams } from './pin-throttle.js';
+import { type CredentialEntryProvenance } from './provenance.js';
+import { type FactorInput, type FactorInputs, type SecretFactorKind } from './suite.js';
+export type CreateCredentialManagerParams = {
+    store: CredentialStoreAPI;
+    /**
+     * This device's identity. NOT required to be a `KeyAgreementIdentity`: a device
+     * that cannot decrypt can still read metadata, and will be able to unwrap by
+     * passphrase once that factor exists. What it cannot do is take the `did`
+     * default in {@link CredentialManager.createKey}.
+     *
+     * It MUST be able to sign, which a reading identity need not: every row this
+     * manager writes carries a signed op, and a device that could write rows no
+     * peer can authenticate would be writing into a lane that has to drop them.
+     */
+    identity: SigningIdentity;
+    /**
+     * Host runtime, propagated rather than constructed here. This package runs on
+     * React Native and in browsers as well as on node, and content keys, IVs and
+     * factor secrets are the values that most need the platform's own CSPRNG
+     * rather than whatever `crypto` a bundler resolved.
+     */
+    runtime: Runtime;
+    /**
+     * The device's one clock, passed in rather than built here.
+     *
+     * Required, and deliberately not defaulted: a connector builds one manager per
+     * transaction, so a manager that constructed its own would start from
+     * `lastWallTime = 0` every time and two of them writing in the same
+     * millisecond would emit an identical `(wallTime, counter, nodeID)` — a
+     * colliding merkle leaf and an order tie with no tiebreak.
+     */
+    hlc: HLC;
+    /**
+     * Who this identity is relative to a key. Defaults to the device answer:
+     * it administers what it owns and nothing else.
+     *
+     * The same port the plugin's query context takes, deliberately — a device
+     * authority refuses a grant recipient gating someone else's key, and a
+     * delegation authority will let an agent gate its controller's, without
+     * either layer growing a predicate of its own.
+     */
+    authority?: CredentialAuthority;
+    /**
+     * How long an unlocked key stays in memory. Eviction is lazy — checked when
+     * the cache is read — because a timer would keep the host process alive and
+     * make every test wait on a clock it does not control.
+     */
+    unlockTTL?: number;
+    /**
+     * Failed-PIN backoff. Its clock comes from `now`, so a caller cannot give the
+     * throttle a different notion of time from the cache's.
+     */
+    pinThrottle?: Omit<PinThrottleParams, 'now'>;
+    /** Injectable so a TTL or backoff test does not sleep. */
+    now?: () => number;
+};
+export type CreateKeyParams = {
+    suite?: number;
+    /** One wrapping, whose factors are an AND. Shorthand for a single-entry `wrappings`. */
+    factors?: Array<FactorInput>;
+    /**
+     * Several wrappings — an OR of ANDs, one per way of opening the key.
+     *
+     * A key addressed to two recipients is not two keys and is not a grant: both
+     * wrappings exist from the first write, which is what a connector needs when
+     * the account owner and the server that runs sync are different DIDs.
+     */
+    wrappings?: Array<Array<FactorInput>>;
+    /**
+     * Who may later grant, rotate and revoke. Defaults to this device, which is
+     * the peer case. A server creating a key on a viewer's behalf passes the
+     * viewer, and stays a recipient rather than the owner.
+     */
+    ownerDID?: string;
+    /**
+     * Resolvers for recipient DIDs that carry no key material of their own
+     * (`did:kokuin:`). Passed per call rather than held on the manager, so a
+     * request-scoped resolver never outlives its request in the cached manager.
+     */
+    methods?: MethodRegistry;
+};
+export type RotateKeyParams = {
+    /**
+     * Migrate to a different ciphersuite. Rotation is the only path between
+     * suites: it already re-encrypts every entry and re-makes every wrapping,
+     * which is exactly what a suite change needs.
+     */
+    suite?: number;
+    /**
+     * Secrets for the surviving factors, keyed by kind — the same prompt
+     * `addFactor` needs, for the same reason: a descriptor holds a salt and a
+     * cost, never the secret, so a wrapping carrying one cannot be re-made at the
+     * new version without it.
+     *
+     * Only the rotating identity's own wrappings can carry a secret factor, since
+     * `addFactor` refuses one on a key it does not administer — so the prompt is
+     * always one the caller is present for.
+     */
+    inputs?: FactorInputs;
+    /** Resolvers for recipient DIDs that need one (`did:kokuin:`), for re-made `did` wrappings. */
+    methods?: MethodRegistry;
+    /**
+     * Overrides the constructed authority for this one call, so a provider-cached
+     * manager holds no request state. No production caller feeds one yet — the
+     * group-grant wiring that will is a follow-up.
+     */
+    authority?: CredentialAuthority;
+};
+/** Optionals shared by the factor-editing verbs `addFactor` and `removeFactor`. */
+export type FactorChangeParams = {
+    /**
+     * Secrets for the factors that SURVIVE the change, keyed by kind — a
+     * descriptor holds a salt, never a secret, so the surviving wrapping's KEK
+     * cannot be re-derived without them.
+     */
+    inputs?: FactorInputs;
+    /** Resolvers for recipient DIDs that need one (`did:kokuin:`), for re-made `did` wrappings. */
+    methods?: MethodRegistry;
+    /** Per-call authority overriding the constructed default. See `RotateKeyParams.authority`. */
+    authority?: CredentialAuthority;
+};
+/** See `grant`. */
+export type GrantKeyParams = {
+    /** Resolvers for recipient DIDs that carry no key material of their own (`did:kokuin:`). */
+    methods?: MethodRegistry;
+    /** Per-call authority overriding the constructed default. See `RotateKeyParams.authority`. */
+    authority?: CredentialAuthority;
+};
+/** See `reKeyEntry`. */
+export type ReKeyEntryParams = {
+    /** Per-call authority overriding the constructed default. See `RotateKeyParams.authority`. */
+    authority?: CredentialAuthority;
+};
+/**
+ * Why a key cannot be opened here, as opposed to not being open yet.
+ *
+ * Carried so that `status` can answer rather than throw: the one call whose job
+ * is to report a key as unreadable must not fail on the key that is unreadable.
+ */
+export type CredentialUnopenableReason = 
+/** A newer peer's ciphersuite. A different build could open it; this one cannot. */
+'unsupported-suite'
+/** No wrapping at the key's current version — a rotation that did not finish. */
+ | 'no-wrapping'
+/** Every wrapping belongs to another recipient. Another device can open it. */
+ | 'not-addressed';
+/**
+ * Derived, never stored. A persisted `unlocked` column would be a belief that
+ * survives a restart it should not.
+ *
+ * `available` is separated from `unlocked` because they differ in what the
+ * caller must do, which is nothing, and in what the machine must do, which is
+ * one unwrap. A `did`-only key is `available` until first read, and a TTL
+ * eviction returns it there rather than to `locked` — no prompt ever becomes
+ * necessary.
+ */
+export type CredentialKeyStatus = {
+    state: 'unlocked';
+} | {
+    state: 'available';
+} | {
+    state: 'locked';
+    /**
+     * One entry per wrapping that could be opened here: an OR of ANDs. Nested
+     * because flattening loses the difference between a key openable by a pin
+     * OR a passphrase and one demanding both, and those are different prompts.
+     * `did` factors are absent — this device supplies them without asking.
+     */
+    unlockOptions: Array<Array<SecretFactorKind>>;
+} | {
+    state: 'unopenable';
+    reason: CredentialUnopenableReason;
+};
+export type CredentialGrantResult = {
+    /** The key version the recipient's wrapping sits at. */
+    version: number;
+    /**
+     * False when the recipient already held a wrapping and nothing was written.
+     * A caller broadcasting the grant emits its frame either way — that is what
+     * makes a repeat grant the retry path for a frame that never arrived.
+     */
+    created: boolean;
+};
+export type CredentialManager = {
+    /** Factor kinds this device can supply. Empty means it can hold no credentials. */
+    availableFactors(): Array<string>;
+    /**
+     * Open a key and hold its content key in memory.
+     *
+     * A `did`-only key needs no call: it opens on demand. This is for the ones
+     * carrying a factor only the user can supply.
+     */
+    unlock(keyID: string, inputs?: FactorInputs): Promise<void>;
+    /** Zero the cached content key. TTL eviction does the same thing. */
+    lock(keyID: string): void;
+    lockAll(): void;
+    status(keyID: string): Promise<CredentialKeyStatus>;
+    /**
+     * Add a factor to THIS device's wrapping, leaving every other recipient's
+     * alone. Adding a `pin` therefore gates this device and no other, which is the
+     * intended granularity.
+     *
+     * `params.inputs` must carry the secret for every factor that SURVIVES the
+     * change, not only the one being added: the new wrapping's key is derived from
+     * all of them, and a descriptor holds a salt, never a secret.
+     */
+    addFactor(keyID: string, factor: FactorInput, params?: FactorChangeParams): Promise<void>;
+    /** Remove a factor kind from this device's wrapping. See `addFactor` on `params.inputs`. */
+    removeFactor(keyID: string, kind: string, params?: FactorChangeParams): Promise<void>;
+    createKey(params?: CreateKeyParams): Promise<string>;
+    /**
+     * Retire this key's content key: mint a fresh one at `version + 1`,
+     * re-encrypt every entry under it and re-make every wrapping. Returns the new
+     * version, which a caller has to carry in the `credential:key-rotate` frame.
+     *
+     * `keyID` and every `entryID` survive, so documents referencing them do not
+     * move. A wrapping survives only if this device can re-make it: `did`-only
+     * ones re-make unattended, and one carrying a secret factor needs that secret
+     * back in `params.inputs`, because re-making a wrapping derives its KEK from
+     * every surviving factor and a descriptor holds a salt, never a secret.
+     *
+     * NOT atomic. This manager holds a resolved store, not a `StoreProvider`, so
+     * it has no transaction to open — a caller wanting all-or-nothing has to build
+     * the manager inside one.
+     */
+    rotate(keyID: string, params?: RotateKeyParams): Promise<number>;
+    /**
+     * Address this key to one more recipient: a `did` wrapping over the SAME
+     * content key at the key's current version. Every entry already written stays
+     * as it is — the recipient opens the key, not a copy of it — and no entry
+     * plaintext is touched. Returns the version the wrapping was made at, which a
+     * caller has to carry in the `credential:key-grant` frame.
+     *
+     * A recipient that already holds a wrapping is a no-op, so the version alone
+     * cannot tell a fresh grant from a re-grant — `created` is what distinguishes
+     * them.
+     *
+     * `recipientWrappableDID` must be RESOLVABLE, not merely a name: a
+     * `did:peer:4` short form carries no document and so no agreement key. Working
+     * out which string that is for a given party is a group question, and this
+     * package does not know what a group is — so it takes the answer rather than
+     * asking.
+     *
+     * `administer`, and the device must be able to open the key: a locked one
+     * fails before the first write rather than persisting half a grant.
+     */
+    grant(keyID: string, recipientWrappableDID: string, params?: GrantKeyParams): Promise<CredentialGrantResult>;
+    listKeys(): Promise<Array<string>>;
+    /** How many wrappings a key carries — one per way of opening it. */
+    countWrappings(keyID: string): Promise<number>;
+    deleteKey(keyID: string): Promise<void>;
+    putEntry(keyID: string, plaintext: Uint8Array): Promise<string>;
+    updateEntry(entryID: string, plaintext: Uint8Array): Promise<void>;
+    readEntry(entryID: string): Promise<Uint8Array>;
+    getEntryProvenance(entryID: string): Promise<CredentialEntryProvenance>;
+    listEntries(keyID: string): Promise<Array<string>>;
+    deleteEntry(entryID: string): Promise<void>;
+    /**
+     * Move an entry onto another key: decrypt under the one it sits on, re-encrypt
+     * under the target's current version, keep the entry id.
+     *
+     * The key is the sharing unit, so sharing one secret means moving it onto a
+     * shared key rather than sharing the key it already sits under, which would
+     * share every other entry beneath that one too. The entry id survives because
+     * it never embedded a key id — every document referencing it stays valid. The
+     * ciphertext does not survive: it is bound to its key, so this is a genuine
+     * re-encryption and the target must be open, not merely named.
+     *
+     * `administer` on BOTH keys. Writing under the target changes what the target
+     * holds, and taking an entry out of the source changes what the source holds.
+     */
+    reKeyEntry(entryID: string, toKeyID: string, params?: ReKeyEntryParams): Promise<void>;
+};
+export declare function createCredentialManager(params: CreateCredentialManagerParams): CredentialManager;