@kubun/credential 0.13.0

package/lib/op.d.ts

@@ -0,0 +1,128 @@
+import { type SigningIdentity } from '@kokuin/token';
+import type { CredentialEntry, CredentialKey, CredentialOpInput, CredentialOpSubjectKind, CredentialTombstoneInput, CredentialWrapping, PutCredentialEntryParams, PutCredentialKeyParams, PutCredentialWrappingParams } from '@kubun/store-credential';
+/**
+ * What the author of a credential row signs.
+ *
+ * Digests rather than bytes, as a grant token does: an op travels beside the row
+ * it speaks for, so repeating the ciphertext in the signature would double every
+ * vault on the wire.
+ *
+ * `contentDigest` is `null` exactly when `deleted` — a tombstone has no content,
+ * and a digest of nothing would be a constant every tombstone shared.
+ */
+export type CredentialOpClaim = {
+    subjectKind: CredentialOpSubjectKind;
+    subjectID: string;
+    keyID: string;
+    keyVersion: number;
+    hlc: string;
+    contentDigest: string | null;
+    deleted: boolean;
+    /**
+     * The content-key branch a wrapping or entry joins: its introducing key-op's
+     * `${hlc}:${opHash}` label, signed so a relay cannot move a row between
+     * branches. Absent on a key-op — a key-op's own label folds its own `opHash`,
+     * which is unknown until after signing, so it is recomputed on receipt rather
+     * than claimed. Absent too on an op minted outside a rotation/create, which
+     * does not yet resolve its branch.
+     */
+    branchID?: string;
+};
+/** `issuer` is the normalized verified `iss` — the only author claim a receiver trusts. */
+export type VerifiedCredentialOp = {
+    issuer: string;
+    claim: CredentialOpClaim;
+};
+/** Which row an op speaks for, for the ops that carry no row of their own. */
+export type CredentialOpSubject = {
+    subjectKind: CredentialOpSubjectKind;
+    subjectID: string;
+    keyID: string;
+    keyVersion: number;
+};
+/** A stored row, tagged with which of the three tables it came from. */
+export type CredentialRowSubject = {
+    kind: 'key';
+    row: CredentialKey;
+} | {
+    kind: 'wrapping';
+    row: CredentialWrapping;
+} | {
+    kind: 'entry';
+    row: CredentialEntry;
+};
+/**
+ * A row about to be written, in the shape the store takes it.
+ *
+ * The counterpart to {@link CredentialRowSubject} for a caller that holds no row
+ * yet — a receiver checking an op against bytes it has not stored. It is also
+ * the shape the signer signs, so the two sides compare the same fields.
+ */
+export type CredentialPutSubject = {
+    kind: 'key';
+    params: PutCredentialKeyParams;
+} | {
+    kind: 'wrapping';
+    params: PutCredentialWrappingParams;
+} | {
+    kind: 'entry';
+    params: PutCredentialEntryParams;
+};
+/**
+ * Mints the signed op for every credential row this device writes.
+ *
+ * Separate from the store because the store holds no identity and does no
+ * crypto: it takes the token as opaque text, exactly as it takes a ciphertext.
+ */
+export type CredentialOpSigner = {
+    key(params: PutCredentialKeyParams, hlc: string): Promise<CredentialOpInput>;
+    /**
+     * `branchID` is the introducing key-op's label — passed by a create/rotate
+     * that just minted that key-op. Omitted elsewhere: an op made outside a
+     * rotation does not yet resolve its branch, and gets an empty label until a
+     * later slice threads the current one out of the read path.
+     */
+    wrapping(params: PutCredentialWrappingParams, hlc: string, branchID?: string): Promise<CredentialOpInput>;
+    /**
+     * Stamped from the entry's own `hlc`, never a second reading of the clock. The
+     * entry row keeps that column and the op repeats it, so the two would
+     * otherwise disagree the moment the clock moved between them. `branchID` as on
+     * {@link CredentialOpSigner.wrapping}.
+     */
+    entry(params: PutCredentialEntryParams, branchID?: string): Promise<CredentialOpInput>;
+    tombstone(subject: CredentialOpSubject, hlc: string): Promise<CredentialOpInput>;
+    /** A tombstone naming its own subject, for a delete that removes several rows. */
+    wrappingTombstone(subject: CredentialOpSubject, hlc: string): Promise<CredentialTombstoneInput>;
+};
+/** The digest of the bytes a row holds, per subject kind. */
+export declare function credentialRowDigest(subject: CredentialRowSubject): string;
+/** The digest of the bytes a row is about to be written with, per subject kind. */
+export declare function credentialPutDigest(subject: CredentialPutSubject): string;
+/** Whether a verified claim speaks for a stored row. */
+export declare function credentialOpMatchesRow(claim: CredentialOpClaim, subject: CredentialRowSubject): boolean;
+/** Whether a verified claim speaks for a row about to be written. */
+export declare function credentialOpMatchesPut(claim: CredentialOpClaim, subject: CredentialPutSubject): boolean;
+export declare function createCredentialOpSigner(identity: SigningIdentity): CredentialOpSigner;
+/**
+ * Order two branch labels, keyless and total.
+ *
+ * The `hlc` halves are compared as strings: the serialized HLC form is
+ * lexically total-ordered by construction (fixed-width ISO wall time, then a
+ * zero-padded counter, then the nodeID), the same property the store's
+ * tombstone check leans on. Two concurrent rotations neither dominate, so the
+ * `opHash` breaks the tie — also lexical, and distinct per op, which is what
+ * makes the order total and identical on every device.
+ */
+export declare function compareBranchIDs(a: string, b: string): number;
+/**
+ * The single branch a keyless party names as the winner: the one whose
+ * introducing key-op dominates by HLC, `opHash` breaking genuine concurrency.
+ * Order-independent — every device folds the same set to the same label.
+ */
+export declare function selectWinningBranch(branchIDs: ReadonlyArray<string>): string;
+/**
+ * Verify an op and extract its claim. Returns `null` (never throws) when the
+ * token is unparseable, unsigned (`alg: 'none'`), or structurally malformed — an
+ * attacker cannot forge an `iss` this way.
+ */
+export declare function verifyCredentialOp(token: string): Promise<VerifiedCredentialOp | null>;

package/lib/op.js

@@ -0,0 +1,304 @@
+import { isVerifiedToken, normalizeDID, stringifyToken, verifyToken } from '@kokuin/token';
+import { toB64U } from '@sozai/codec';
+import { credentialEntryDigest, credentialKeyDigest, credentialWrappingDigest, digestParts } from './digest.js';
+/** The digest of the bytes a row holds, per subject kind. */ export function credentialRowDigest(subject) {
+    switch(subject.kind){
+        case 'key':
+            return credentialKeyDigest({
+                ownerDID: subject.row.owner_did,
+                suite: subject.row.suite,
+                version: subject.row.version,
+                state: subject.row.state
+            });
+        case 'wrapping':
+            return credentialWrappingDigest({
+                wrappingID: subject.row.wrapping_id,
+                recipientDID: subject.row.recipient_did,
+                iv: toB64U(new Uint8Array(subject.row.iv)),
+                wrappedKey: toB64U(new Uint8Array(subject.row.wrapped_key)),
+                factors: subject.row.factors
+            });
+        case 'entry':
+            return credentialEntryDigest({
+                entryID: subject.row.entry_id,
+                iv: toB64U(new Uint8Array(subject.row.iv)),
+                ciphertext: toB64U(new Uint8Array(subject.row.ciphertext)),
+                hlc: subject.row.hlc
+            });
+    }
+}
+/** The digest of the bytes a row is about to be written with, per subject kind. */ export function credentialPutDigest(subject) {
+    switch(subject.kind){
+        case 'key':
+            return credentialKeyDigest({
+                ownerDID: subject.params.ownerDID,
+                suite: subject.params.suite,
+                version: subject.params.version,
+                state: subject.params.state
+            });
+        case 'wrapping':
+            return credentialWrappingDigest({
+                wrappingID: subject.params.wrappingID,
+                // An omitted recipient and an explicit null are the same wrapping, as
+                // the signer folds them.
+                recipientDID: subject.params.recipientDID ?? null,
+                iv: toB64U(subject.params.iv),
+                wrappedKey: toB64U(subject.params.wrappedKey),
+                factors: subject.params.factors
+            });
+        case 'entry':
+            return credentialEntryDigest({
+                entryID: subject.params.entryID,
+                iv: toB64U(subject.params.iv),
+                ciphertext: toB64U(subject.params.ciphertext),
+                hlc: subject.params.hlc
+            });
+    }
+}
+/**
+ * Whether a verified claim speaks for exactly these bytes under exactly this
+ * identity.
+ *
+ * The identifiers are checked along with the digest: a claim over another row's
+ * content would otherwise authenticate this one as soon as the two held the same
+ * bytes, which two wrappings of the same key routinely do not but two
+ * empty-state keys would. `keyID` matters beyond that — it is the column the
+ * sync lane buckets a vault by, so an op filed under another key's id would
+ * travel with the wrong set.
+ *
+ * `stamp` is the row's own `hlc` where the row has one, which is entries only.
+ * It has to equal the claim's: the op row keeps the claim's stamp and the entry
+ * row keeps its own, and the two disagreeing would order a row differently from
+ * the op that speaks for it.
+ */ function matchesClaim(claim, subject, contentDigest) {
+    return claim.subjectKind === subject.kind && claim.subjectID === subject.subjectID && claim.keyID === subject.keyID && claim.keyVersion === subject.keyVersion && (subject.stamp == null || claim.hlc === subject.stamp) && !claim.deleted && claim.contentDigest === contentDigest;
+}
+/** Whether a verified claim speaks for a stored row. */ export function credentialOpMatchesRow(claim, subject) {
+    const identity = subject.kind === 'key' ? {
+        kind: 'key',
+        subjectID: subject.row.key_id,
+        keyID: subject.row.key_id,
+        keyVersion: subject.row.version
+    } : subject.kind === 'wrapping' ? {
+        kind: 'wrapping',
+        subjectID: subject.row.wrapping_id,
+        keyID: subject.row.key_id,
+        keyVersion: subject.row.key_version
+    } : {
+        kind: 'entry',
+        subjectID: subject.row.entry_id,
+        keyID: subject.row.key_id,
+        keyVersion: subject.row.key_version,
+        stamp: subject.row.hlc
+    };
+    return matchesClaim(claim, identity, credentialRowDigest(subject));
+}
+/** Whether a verified claim speaks for a row about to be written. */ export function credentialOpMatchesPut(claim, subject) {
+    const identity = subject.kind === 'key' ? {
+        kind: 'key',
+        subjectID: subject.params.keyID,
+        keyID: subject.params.keyID,
+        keyVersion: subject.params.version
+    } : subject.kind === 'wrapping' ? {
+        kind: 'wrapping',
+        subjectID: subject.params.wrappingID,
+        keyID: subject.params.keyID,
+        keyVersion: subject.params.keyVersion
+    } : {
+        kind: 'entry',
+        subjectID: subject.params.entryID,
+        keyID: subject.params.keyID,
+        keyVersion: subject.params.keyVersion,
+        stamp: subject.params.hlc
+    };
+    return matchesClaim(claim, identity, credentialPutDigest(subject));
+}
+async function signOp(identity, claim) {
+    const signed = await identity.signToken({
+        ...claim
+    }, {
+        embedLongForm: true
+    });
+    const opJWT = stringifyToken(signed);
+    return {
+        keyID: claim.keyID,
+        // Normalized, unlike a wrapping's recipient: this one is compared against a
+        // key's owner and against a verified issuer, never resolved to a document.
+        authorDID: normalizeDID(identity.id),
+        hlc: claim.hlc,
+        opJWT,
+        // The token addresses itself, the way the graph mutation log addresses a
+        // mutation by its hash.
+        opHash: digestParts([
+            opJWT
+        ]),
+        // A wrapping or entry mirrors the branch it signed; anything without one
+        // gets the empty label. A key-op overrides this from its own `opHash`.
+        branchID: claim.branchID ?? ''
+    };
+}
+export function createCredentialOpSigner(identity) {
+    async function tombstone(subject, hlc) {
+        return await signOp(identity, {
+            subjectKind: subject.subjectKind,
+            subjectID: subject.subjectID,
+            keyID: subject.keyID,
+            keyVersion: subject.keyVersion,
+            hlc,
+            contentDigest: null,
+            deleted: true
+        });
+    }
+    return {
+        async key (params, hlc) {
+            const input = await signOp(identity, {
+                subjectKind: 'key',
+                subjectID: params.keyID,
+                keyID: params.keyID,
+                keyVersion: params.version,
+                hlc,
+                contentDigest: credentialKeyDigest({
+                    ownerDID: params.ownerDID,
+                    suite: params.suite,
+                    version: params.version,
+                    state: params.state
+                }),
+                deleted: false
+            });
+            // The key-op labels its own branch. It cannot claim this in the signed
+            // token — the label folds `opHash`, which the signature produces — so it
+            // rides on the input and a receiver recomputes it from the op's `hlc` and
+            // `opHash`, which is what authenticates it.
+            return {
+                ...input,
+                branchID: `${hlc}:${input.opHash}`
+            };
+        },
+        async wrapping (params, hlc, branchID) {
+            return await signOp(identity, {
+                subjectKind: 'wrapping',
+                subjectID: params.wrappingID,
+                keyID: params.keyID,
+                keyVersion: params.keyVersion,
+                hlc,
+                contentDigest: credentialWrappingDigest({
+                    wrappingID: params.wrappingID,
+                    // An omitted recipient and an explicit null are the same wrapping, and
+                    // the stored row keeps only one of the two spellings.
+                    recipientDID: params.recipientDID ?? null,
+                    iv: toB64U(params.iv),
+                    wrappedKey: toB64U(params.wrappedKey),
+                    factors: params.factors
+                }),
+                deleted: false,
+                branchID
+            });
+        },
+        async entry (params, branchID) {
+            return await signOp(identity, {
+                subjectKind: 'entry',
+                subjectID: params.entryID,
+                keyID: params.keyID,
+                keyVersion: params.keyVersion,
+                hlc: params.hlc,
+                contentDigest: credentialEntryDigest({
+                    entryID: params.entryID,
+                    iv: toB64U(params.iv),
+                    ciphertext: toB64U(params.ciphertext),
+                    hlc: params.hlc
+                }),
+                deleted: false,
+                branchID
+            });
+        },
+        tombstone,
+        async wrappingTombstone (subject, hlc) {
+            return {
+                ...await tombstone(subject, hlc),
+                subjectID: subject.subjectID
+            };
+        }
+    };
+}
+function isSubjectKind(value) {
+    return value === 'key' || value === 'wrapping' || value === 'entry';
+}
+/**
+ * Split a `branchID` into its `hlc` and `opHash` halves.
+ *
+ * The label is `${hlc}:${opHash}`, and both halves — an HLC and a DID nodeID —
+ * carry their own colons, but `opHash` is base64url and carries none, so the
+ * LAST colon is the boundary however many precede it.
+ */ function splitBranchID(branchID) {
+    const boundary = branchID.lastIndexOf(':');
+    return boundary < 0 ? {
+        hlc: branchID,
+        opHash: ''
+    } : {
+        hlc: branchID.slice(0, boundary),
+        opHash: branchID.slice(boundary + 1)
+    };
+}
+/**
+ * Order two branch labels, keyless and total.
+ *
+ * The `hlc` halves are compared as strings: the serialized HLC form is
+ * lexically total-ordered by construction (fixed-width ISO wall time, then a
+ * zero-padded counter, then the nodeID), the same property the store's
+ * tombstone check leans on. Two concurrent rotations neither dominate, so the
+ * `opHash` breaks the tie — also lexical, and distinct per op, which is what
+ * makes the order total and identical on every device.
+ */ export function compareBranchIDs(a, b) {
+    const left = splitBranchID(a);
+    const right = splitBranchID(b);
+    if (left.hlc !== right.hlc) {
+        return left.hlc < right.hlc ? -1 : 1;
+    }
+    return left.opHash < right.opHash ? -1 : left.opHash > right.opHash ? 1 : 0;
+}
+/**
+ * The single branch a keyless party names as the winner: the one whose
+ * introducing key-op dominates by HLC, `opHash` breaking genuine concurrency.
+ * Order-independent — every device folds the same set to the same label.
+ */ export function selectWinningBranch(branchIDs) {
+    if (branchIDs.length === 0) {
+        throw new RangeError('selectWinningBranch requires at least one branchID');
+    }
+    return branchIDs.reduce((winner, candidate)=>compareBranchIDs(candidate, winner) > 0 ? candidate : winner);
+}
+/**
+ * Verify an op and extract its claim. Returns `null` (never throws) when the
+ * token is unparseable, unsigned (`alg: 'none'`), or structurally malformed — an
+ * attacker cannot forge an `iss` this way.
+ */ export async function verifyCredentialOp(token) {
+    let verified;
+    try {
+        verified = await verifyToken(token);
+    } catch  {
+        return null;
+    }
+    if (!isVerifiedToken(verified)) {
+        return null;
+    }
+    const { iss, subjectKind, subjectID, keyID, keyVersion, hlc, contentDigest, deleted, branchID } = verified.payload;
+    if (!isSubjectKind(subjectKind) || typeof subjectID !== 'string' || typeof keyID !== 'string' || typeof keyVersion !== 'number' || typeof hlc !== 'string' || typeof deleted !== 'boolean' || // A live op with no digest would authenticate any bytes at all, so the two
+    // fields are checked against each other rather than one at a time.
+    (deleted ? contentDigest !== null : typeof contentDigest !== 'string') || // Optional — a key-op omits it — but a present one must be the signed string
+    // a receiver reads as the row's branch label.
+    branchID != null && typeof branchID !== 'string') {
+        return null;
+    }
+    return {
+        issuer: normalizeDID(iss),
+        claim: {
+            subjectKind,
+            subjectID,
+            keyID,
+            keyVersion,
+            hlc,
+            contentDigest: contentDigest,
+            deleted,
+            branchID: branchID
+        }
+    };
+}

package/lib/pin-throttle.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Attempts allowed before any delay. A mistyped PIN is the common case and
+ * should not cost the user a wait.
+ */
+export declare const DEFAULT_FREE_ATTEMPTS = 3;
+/** First delay after the free attempts, doubling from here. */
+export declare const DEFAULT_BASE_DELAY = 1000;
+/** Ceiling on the doubling. Past this the wait is punitive rather than useful. */
+export declare const DEFAULT_MAX_DELAY: number;
+export type PinThrottleParams = {
+    freeAttempts?: number;
+    baseDelay?: number;
+    maxDelay?: number;
+    /** Injectable so a backoff test does not sleep. */
+    now?: () => number;
+};
+/**
+ * Per-key failed-PIN counter with exponential backoff.
+ *
+ * In memory only. A restart resets it, which is the honest position rather than
+ * a gap: anyone able to restart the process to dodge the counter can also read
+ * the database, so persisting it would buy nothing while adding a write on every
+ * failed attempt — a denial-of-service surface reachable by anyone who can guess
+ * wrong repeatedly.
+ *
+ * The value it does carry is against the borrowed unlocked device, where the
+ * `did` factor is non-extractable and the attacker cannot take the ciphertext
+ * elsewhere to grind it. There, 10^4 combinations against a doubling delay is
+ * not a search anyone completes by hand.
+ */
+export type PinThrottle = {
+    /**
+     * Milliseconds until this key accepts another attempt, or 0 if it accepts one
+     * now. Called BEFORE the KDF runs: a refusal that still derives costs the
+     * defender exactly what it costs the attacker.
+     */
+    retryAfter(keyID: string): number;
+    /** How many attempts remain before a delay begins. */
+    attemptsRemaining(keyID: string): number;
+    recordFailure(keyID: string): void;
+    /** Clear the count. A correct PIN ends the sequence. */
+    recordSuccess(keyID: string): void;
+};
+export declare function createPinThrottle(params?: PinThrottleParams): PinThrottle;

package/lib/pin-throttle.js

@@ -0,0 +1,48 @@
+/**
+ * Attempts allowed before any delay. A mistyped PIN is the common case and
+ * should not cost the user a wait.
+ */ export const DEFAULT_FREE_ATTEMPTS = 3;
+/** First delay after the free attempts, doubling from here. */ export const DEFAULT_BASE_DELAY = 1000;
+/** Ceiling on the doubling. Past this the wait is punitive rather than useful. */ export const DEFAULT_MAX_DELAY = 15 * 60 * 1000;
+export function createPinThrottle(params = {}) {
+    const freeAttempts = params.freeAttempts ?? DEFAULT_FREE_ATTEMPTS;
+    const baseDelay = params.baseDelay ?? DEFAULT_BASE_DELAY;
+    const maxDelay = params.maxDelay ?? DEFAULT_MAX_DELAY;
+    const now = params.now ?? Date.now;
+    const attempts = new Map();
+    function delayAfter(failures) {
+        // `<`, not `<=`: with the allowance spent, `attemptsRemaining` reads 0 and
+        // the next attempt must actually be refused. The two have to agree, or the
+        // caller shows "0 attempts left" while another one still goes through.
+        if (failures < freeAttempts) {
+            return 0;
+        }
+        // 1s, 2s, 4s … so the first failure past the allowance is barely felt and
+        // the tenth is not worth waiting out.
+        return Math.min(baseDelay * 2 ** (failures - freeAttempts), maxDelay);
+    }
+    return {
+        retryAfter (keyID) {
+            const record = attempts.get(keyID);
+            if (record == null) {
+                return 0;
+            }
+            const elapsed = now() - record.lastFailureAt;
+            return Math.max(0, delayAfter(record.failures) - elapsed);
+        },
+        attemptsRemaining (keyID) {
+            const record = attempts.get(keyID);
+            return Math.max(0, freeAttempts - (record?.failures ?? 0));
+        },
+        recordFailure (keyID) {
+            const record = attempts.get(keyID);
+            attempts.set(keyID, {
+                failures: (record?.failures ?? 0) + 1,
+                lastFailureAt: now()
+            });
+        },
+        recordSuccess (keyID) {
+            attempts.delete(keyID);
+        }
+    };
+}

package/lib/provenance.d.ts

@@ -0,0 +1,6 @@
+import type { CredentialEntryWithProvenance } from '@kubun/store-credential';
+export type CredentialEntryProvenance = {
+    updatedAt: string | null;
+    writerDID: string | null;
+};
+export declare function entryProvenanceFields(entry: Pick<CredentialEntryWithProvenance, 'hlc' | 'author_did'>): CredentialEntryProvenance;

package/lib/provenance.js

@@ -0,0 +1,8 @@
+import { HLC } from '@kubun/hlc';
+export function entryProvenanceFields(entry) {
+    const timestamp = HLC.tryParse(entry.hlc);
+    return {
+        updatedAt: timestamp == null ? null : new Date(timestamp.wallTime).toISOString(),
+        writerDID: entry.author_did
+    };
+}

package/lib/suite.d.ts

@@ -0,0 +1,112 @@
+import type { KeyAgreementIdentity, MethodRegistry } from '@kokuin/token';
+import type { CredentialFactorDescriptor } from '@kubun/store-credential';
+import type { Runtime } from '@sozai/runtime';
+/** X25519 / HKDF-SHA256 / Argon2id / A256GCM. */
+export declare const SUITE_KUBUN_CRED_1 = 1;
+/** Argon2id cost, in the RFC 9106 parameter names: memory KiB, passes, lanes. */
+export type Argon2Cost = {
+    m: number;
+    t: number;
+    p: number;
+};
+/**
+ * Per-wrapping, not per-suite: the suite fixes the algorithm and the wrapping
+ * fixes the cost, so cost rises with hardware without minting a suite.
+ *
+ * OWASP's first Argon2id configuration. Measured at 340ms on an M2 Max; the
+ * 46MiB/t=1 alternative costs the same time for 2.4x the memory, which is the
+ * scarcer resource on the Expo and browser targets.
+ */
+export declare const DEFAULT_ARGON2_COST: Argon2Cost;
+/** A kind whose secret comes from the user rather than from key material. */
+export type SecretFactorKind = 'passphrase' | 'pin';
+export type FactorInput = {
+    kind: 'did';
+    recipientDID: string;
+} | {
+    kind: SecretFactorKind;
+    input: Uint8Array;
+    cost?: Argon2Cost;
+};
+/**
+ * User-supplied factor inputs for an unwrap, keyed by kind.
+ *
+ * Keyed by kind rather than by descriptor index because a caller supplies "my
+ * PIN", not "the secret for descriptor 3". That makes two factors of the same
+ * kind in one wrapping ambiguous, so {@link validateFactorList} refuses them at
+ * creation.
+ */
+export type FactorInputs = Partial<Record<SecretFactorKind, Uint8Array>>;
+export type CredentialSuite = {
+    readonly id: number;
+    readonly name: string;
+    /** Fresh content key for a new key version. */
+    generateContentKey(runtime: Runtime): Uint8Array;
+    wrap(params: WrapParams): Promise<WrapResult>;
+    unwrap(params: UnwrapParams): Promise<Uint8Array>;
+    encryptEntry(params: EncryptEntryParams): {
+        iv: Uint8Array;
+        ciphertext: Uint8Array;
+    };
+    decryptEntry(params: DecryptEntryParams): Uint8Array;
+};
+export type WrapParams = {
+    runtime: Runtime;
+    contentKey: Uint8Array;
+    factors: Array<FactorInput>;
+    wrappingID: string;
+    keyID: string;
+    keyVersion: number;
+    /**
+     * Resolvers for recipient DIDs that carry no key material of their own
+     * (`did:kokuin:`). Absent leaves self-contained recipients (`did:key`,
+     * `did:peer:4`) resolving as before and any other DID failing closed.
+     */
+    methods?: MethodRegistry;
+};
+export type WrapResult = {
+    descriptors: Array<CredentialFactorDescriptor>;
+    iv: Uint8Array;
+    /** `ciphertext ‖ tag`. The IV travels beside it, as it does for an entry. */
+    wrappedKey: Uint8Array;
+};
+export type UnwrapParams = {
+    identity: KeyAgreementIdentity | null;
+    descriptors: Array<CredentialFactorDescriptor>;
+    /** Raw user input per kind. Absent for a `did`-only wrapping. */
+    inputs?: FactorInputs;
+    iv: Uint8Array;
+    wrappedKey: Uint8Array;
+    wrappingID: string;
+    keyID: string;
+    keyVersion: number;
+};
+export type EncryptEntryParams = {
+    runtime: Runtime;
+    contentKey: Uint8Array;
+    plaintext: Uint8Array;
+    keyID: string;
+    keyVersion: number;
+    entryID: string;
+};
+export type DecryptEntryParams = {
+    contentKey: Uint8Array;
+    iv: Uint8Array;
+    ciphertext: Uint8Array;
+    keyID: string;
+    keyVersion: number;
+    entryID: string;
+};
+/**
+ * Factor-list rules that hold regardless of suite.
+ *
+ * A second `passphrase` or `pin` is refused because unwrap inputs are keyed by
+ * kind: it could only ever be handed the same secret as the first, making an AND
+ * that reads as two factors and is one. Repeated `did` factors are fine and
+ * meaningful — each descriptor carries its own recipient, so "Alice AND Bob" is
+ * a list of two.
+ */
+export declare function validateFactorList(kinds: Array<string>): void;
+/** The suite a key names, or `UnsupportedCredentialSuite` — never a silent skip. */
+export declare function getSuite(id: number): CredentialSuite;
+export declare function isSupportedSuite(id: number): boolean;