@kubun/credential 0.13.0

package/LICENSE.md

@@ -0,0 +1,57 @@
+# The Prosperity Public License 3.0.0
+
+Contributor: Paul Le Cam
+
+Source Code: https://github.com/PaulLeCam/kubun
+
+## Purpose
+
+This license allows you to use and share this software for noncommercial purposes for free and to try this software for commercial purposes for thirty days.
+
+## Agreement
+
+In order to receive this license, you have to agree to its rules.  Those rules are both obligations under that agreement and conditions to your license.  Don't do anything with this software that triggers a rule you can't or won't follow.
+
+## Notices
+
+Make sure everyone who gets a copy of any part of this software from you, with or without changes, also gets the text of this license and the contributor and source code lines above.
+
+## Commercial Trial
+
+Limit your use of this software for commercial purposes to a thirty-day trial period.  If you use this software for work, your company gets one trial period for all personnel, not one trial per person.
+
+## Contributions Back
+
+Developing feedback, changes, or additions that you contribute back to the contributor on the terms of a standardized public software license such as [the Blue Oak Model License 1.0.0](https://blueoakcouncil.org/license/1.0.0), [the Apache License 2.0](https://www.apache.org/licenses/LICENSE-2.0.html), [the MIT license](https://spdx.org/licenses/MIT.html), or [the two-clause BSD license](https://spdx.org/licenses/BSD-2-Clause.html) doesn't count as use for a commercial purpose.
+
+## Personal Uses
+
+Personal use for research, experiment, and testing for the benefit of public knowledge, personal study, private entertainment, hobby projects, amateur pursuits, or religious observance, without any anticipated commercial application, doesn't count as use for a commercial purpose.
+
+## Noncommercial Organizations
+
+Use by any charitable organization, educational institution, public research organization, public safety or health organization, environmental protection organization, or government institution doesn't count as use for a commercial purpose regardless of the source of funding or obligations resulting from the funding.
+
+## Defense
+
+Don't make any legal claim against anyone accusing this software, with or without changes, alone or with other technology, of infringing any patent.
+
+## Copyright
+
+The contributor licenses you to do everything with this software that would otherwise infringe their copyright in it.
+
+## Patent
+
+The contributor licenses you to do everything with this software that would otherwise infringe any patents they can license or become able to license.
+
+## Reliability
+
+The contributor can't revoke this license.
+
+## Excuse
+
+You're excused for unknowingly breaking [Notices](#notices) if you take all practical steps to comply within thirty days of learning you broke the rule.
+
+## No Liability
+
+***As far as the law allows, this software comes as is, without any warranty or condition, and the contributor won't be liable to anyone for any damages related to this software or this license, under any kind of legal claim.***

package/lib/authority.d.ts

@@ -0,0 +1,29 @@
+import type { CredentialKey, CredentialStoreAPI } from '@kubun/store-credential';
+/**
+ * Two authority levels, distinct only for a non-owner: a recipient already holds a
+ * wrapping that decrypts, so `read` (serve the ciphertext) is free to grant, while
+ * `administer` (grant/rotate/revoke) by a non-owner would make a key un-revokable.
+ */
+export type CredentialAuthorization = 'read' | 'administer';
+export type CredentialAuthorityParams = {
+    key: CredentialKey;
+    /** The request's store, so an answer may consult rows the key alone does not carry. */
+    store: CredentialStoreAPI;
+};
+export type CredentialAuthority = {
+    /**
+     * The DID a key minted by this viewer belongs to.
+     *
+     * Asked rather than assumed because under delegation the owner is neither the
+     * client's input nor the signer, but what the chain resolves to.
+     */
+    ownerForNewKey(): Promise<string>;
+    authorize(authorization: CredentialAuthorization, params: CredentialAuthorityParams): Promise<boolean>;
+};
+/**
+ * The stand-in until ownership is a controller/agent capability chain: the viewer
+ * is one device and owns what it minted. `owner_did` is normalized (compare
+ * normalized, or a `did:peer:4` long-form viewer is refused its own vault);
+ * `recipient_did` is a key-resolution input, never normalized, so it is folded here.
+ */
+export declare function createDeviceAuthority(rawViewerDID: string): CredentialAuthority;

package/lib/authority.js

@@ -0,0 +1,26 @@
+import { normalizeDID } from '@kokuin/token';
+/**
+ * The stand-in until ownership is a controller/agent capability chain: the viewer
+ * is one device and owns what it minted. `owner_did` is normalized (compare
+ * normalized, or a `did:peer:4` long-form viewer is refused its own vault);
+ * `recipient_did` is a key-resolution input, never normalized, so it is folded here.
+ */ export function createDeviceAuthority(rawViewerDID) {
+    const viewerDID = normalizeDID(rawViewerDID);
+    return {
+        async ownerForNewKey () {
+            return viewerDID;
+        },
+        async authorize (authorization, { key, store }) {
+            if (normalizeDID(key.owner_did) === viewerDID) {
+                return true;
+            }
+            if (authorization === 'administer') {
+                return false;
+            }
+            // Current version only: a recipient left behind by a rotation or revocation
+            // must read as "not a recipient", not as history.
+            const wrappings = await store.listWrappings(key.key_id, key.version);
+            return wrappings.some((wrapping)=>wrapping.recipient_did != null && normalizeDID(wrapping.recipient_did) === viewerDID);
+        }
+    };
+}

package/lib/builder.d.ts

@@ -0,0 +1,82 @@
+import { type MethodRegistry } from '@kokuin/token';
+import type { CredentialFactorDescriptor } from '@kubun/store-credential';
+import type { Runtime } from '@sozai/runtime';
+import { type FactorInput } from './suite.js';
+/**
+ * Credential material built as values, with no store and no private key.
+ *
+ * The party that runs an OAuth flow is the only one holding the token in
+ * plaintext, and it is frequently a client with no credential database of its
+ * own. It can still produce everything the server needs to persist: sender-side
+ * ECDH-ES consumes only the recipients' *published* agreement keys, so a client
+ * wraps a content key to a server's DID without that server participating and
+ * without holding any private key itself.
+ *
+ * Nothing in this module imports `CredentialStoreAPI`, and a test builds a key
+ * with no store in scope to keep that true. A builder that quietly grew a store
+ * dependency would compile and would be unusable by the caller it exists for.
+ */
+/** Enough to encrypt an entry under a key. */
+export type CredentialKeyMaterial = {
+    keyID: string;
+    ownerDID: string;
+    suite: number;
+    version: number;
+    /**
+     * Never transmitted. The wrappings are how this reaches a recipient; sending
+     * it beside them would make every wrapping decorative.
+     */
+    contentKey: Uint8Array;
+};
+export type BuiltWrapping = {
+    wrappingID: string;
+    keyID: string;
+    keyVersion: number;
+    factors: Array<CredentialFactorDescriptor>;
+    iv: Uint8Array;
+    wrappedKey: Uint8Array;
+    recipientDID: string | null;
+};
+export type BuiltKey = CredentialKeyMaterial & {
+    wrappings: Array<BuiltWrapping>;
+};
+export type BuildKeyParams = {
+    runtime: Runtime;
+    /**
+     * Who may later grant, rotate and revoke — not necessarily anyone who can
+     * decrypt. On a peer this is also the sole recipient; on a multi-tenant server
+     * the owner is the viewer and the server is a recipient.
+     */
+    ownerDID: string;
+    suite?: number;
+    /**
+     * One inner array per wrapping, holding the factors that wrapping ANDs
+     * together. The outer array is the OR: any one wrapping opens the key.
+     */
+    wrappings: Array<Array<FactorInput>>;
+    /** Resolvers for recipient DIDs that carry no key material of their own (`did:kokuin:`). */
+    methods?: MethodRegistry;
+};
+export type BuiltEntry = {
+    entryID: string;
+    keyID: string;
+    keyVersion: number;
+    iv: Uint8Array;
+    ciphertext: Uint8Array;
+};
+export type BuildEntryParams = {
+    runtime: Runtime;
+    key: CredentialKeyMaterial;
+    plaintext: Uint8Array;
+};
+/**
+ * Mint a key, its content key and one wrapping per recipient set.
+ *
+ * `ownerDID` is normalized because it is an equality key — a lookup and an
+ * authorization comparison both match on it — while a wrapping's recipient is
+ * not, because it is a key-resolution input and folding a `did:peer:4` long form
+ * would make the wrapping unopenable.
+ */
+export declare function buildCredentialKey(params: BuildKeyParams): Promise<BuiltKey>;
+/** Encrypt one value under a key already built or already open. */
+export declare function buildCredentialEntry(params: BuildEntryParams): BuiltEntry;

package/lib/builder.js

@@ -0,0 +1,76 @@
+import { normalizeDID } from '@kokuin/token';
+import { CredentialEntryID, CredentialKeyID } from '@kubun/id';
+import { InvalidCredentialFactors } from './errors.js';
+import { getSuite, SUITE_KUBUN_CRED_1 } from './suite.js';
+/**
+ * Mint a key, its content key and one wrapping per recipient set.
+ *
+ * `ownerDID` is normalized because it is an equality key — a lookup and an
+ * authorization comparison both match on it — while a wrapping's recipient is
+ * not, because it is a key-resolution input and folding a `did:peer:4` long form
+ * would make the wrapping unopenable.
+ */ export async function buildCredentialKey(params) {
+    if (params.wrappings.length === 0) {
+        throw new InvalidCredentialFactors('a key needs at least one wrapping');
+    }
+    const { runtime } = params;
+    const suiteID = params.suite ?? SUITE_KUBUN_CRED_1;
+    const suite = getSuite(suiteID);
+    const ownerDID = normalizeDID(params.ownerDID);
+    const version = 1;
+    const keyID = CredentialKeyID.create(ownerDID, runtime.getRandomValues(new Uint8Array(16))).toString();
+    const contentKey = suite.generateContentKey(runtime);
+    const wrappings = [];
+    for (const factors of params.wrappings){
+        const wrappingID = runtime.getRandomID();
+        const { descriptors, iv, wrappedKey } = await suite.wrap({
+            runtime,
+            contentKey,
+            factors,
+            wrappingID,
+            keyID,
+            keyVersion: version,
+            methods: params.methods
+        });
+        wrappings.push({
+            wrappingID,
+            keyID,
+            keyVersion: version,
+            factors: descriptors,
+            iv,
+            wrappedKey,
+            // Populated only for the single-`did` case. A `[did, pin]` wrapping is not
+            // openable by its recipient alone, so recording one would let a lookup
+            // conclude the key opens on that device when it does not.
+            recipientDID: factors.length === 1 && factors[0]?.kind === 'did' ? factors[0].recipientDID : null
+        });
+    }
+    return {
+        keyID,
+        ownerDID,
+        suite: suiteID,
+        version,
+        contentKey,
+        wrappings
+    };
+}
+/** Encrypt one value under a key already built or already open. */ export function buildCredentialEntry(params) {
+    const { runtime, key } = params;
+    const suite = getSuite(key.suite);
+    const entryID = CredentialEntryID.create(key.ownerDID, runtime.getRandomValues(new Uint8Array(16))).toString();
+    const { iv, ciphertext } = suite.encryptEntry({
+        runtime,
+        contentKey: key.contentKey,
+        plaintext: params.plaintext,
+        keyID: key.keyID,
+        keyVersion: key.version,
+        entryID
+    });
+    return {
+        entryID,
+        keyID: key.keyID,
+        keyVersion: key.version,
+        iv,
+        ciphertext
+    };
+}

package/lib/digest.d.ts

@@ -0,0 +1,53 @@
+import type { CredentialFactorDescriptor } from '@kubun/store-credential';
+/**
+ * Length-prefixed, not delimited. A separator would only be unambiguous while
+ * every part stayed inside an alphabet that excludes it — which is true of
+ * base64url and not of a DID or a factor kind, so the framing would be a
+ * property of the inputs rather than of the digest.
+ *
+ * blake3 for the React Native / browser / node triple, as elsewhere here.
+ */
+export declare function digestParts(parts: Array<string>): string;
+/** A key's public record, as the wire spells it. */
+export type CredentialKeyDigestInput = {
+    ownerDID: string;
+    suite: number;
+    version: number;
+    state: string;
+};
+/** One wrapping, with its byte fields base64url-encoded. */
+export type CredentialWrappingDigestInput = {
+    wrappingID: string;
+    /** `null` for a wrapping addressed to no DID — a passphrase-only one. */
+    recipientDID: string | null;
+    iv: string;
+    wrappedKey: string;
+    factors: Array<CredentialFactorDescriptor>;
+};
+/** One entry, with its byte fields base64url-encoded. */
+export type CredentialEntryDigestInput = {
+    entryID: string;
+    iv: string;
+    ciphertext: string;
+    hlc: string;
+};
+/**
+ * Every field of the key's public record. `created_at` is absent deliberately:
+ * it is the local write time, and two devices holding the same key disagree
+ * about it.
+ */
+export declare function credentialKeyDigest(key: CredentialKeyDigestInput): string;
+/** Every field of the wrapping a receiver writes, including the factor descriptors. */
+export declare function credentialWrappingDigest(wrapping: CredentialWrappingDigestInput): string;
+/**
+ * Entries in `entryID` order, so the same set digests identically wherever it is
+ * assembled. `listEntries` order is the store's, and two devices need not agree
+ * on it.
+ *
+ * `hlc` contributes along with the ciphertext: the receiver writes it into the
+ * entry row, and an input the receiver stores that the signature does not cover
+ * is an unauthenticated write.
+ */
+export declare function credentialEntriesDigest(entries: ReadonlyArray<CredentialEntryDigestInput>): string;
+/** One entry's digest is the one-element set's — the same framing, not a second one. */
+export declare function credentialEntryDigest(entry: CredentialEntryDigestInput): string;

package/lib/digest.js

@@ -0,0 +1,82 @@
+import { blake3 } from '@noble/hashes/blake3.js';
+import { fromUTF, toB64U } from '@sozai/codec';
+/**
+ * Canonical JSON: object keys sorted, array order kept.
+ *
+ * The two halves are deliberate. A `params` record is an unordered bag whose
+ * key order is whatever a JSON round trip happened to preserve, so digesting it
+ * as written would make the digest a property of the serializer. A `factors`
+ * array is not: the KEK derivation concatenates factor secrets in order and the
+ * descriptors are bound into the wrapping's AAD, so a permuted list is a
+ * different wrapping rather than the same one written differently.
+ */ function canonicalJSON(value) {
+    if (value === null || typeof value !== 'object') {
+        return JSON.stringify(value) ?? 'null';
+    }
+    if (Array.isArray(value)) {
+        return `[${value.map(canonicalJSON).join(',')}]`;
+    }
+    const entries = Object.entries(value).sort(([left], [right])=>left < right ? -1 : left > right ? 1 : 0);
+    return `{${entries.map(([key, item])=>`${JSON.stringify(key)}:${canonicalJSON(item)}`).join(',')}}`;
+}
+/**
+ * Length-prefixed, not delimited. A separator would only be unambiguous while
+ * every part stayed inside an alphabet that excludes it — which is true of
+ * base64url and not of a DID or a factor kind, so the framing would be a
+ * property of the inputs rather than of the digest.
+ *
+ * blake3 for the React Native / browser / node triple, as elsewhere here.
+ */ export function digestParts(parts) {
+    const framed = parts.map((part)=>`${part.length}:${part}`).join('');
+    return toB64U(blake3(fromUTF(framed), {
+        dkLen: 32
+    }));
+}
+/**
+ * Every field of the key's public record. `created_at` is absent deliberately:
+ * it is the local write time, and two devices holding the same key disagree
+ * about it.
+ */ export function credentialKeyDigest(key) {
+    return digestParts([
+        key.ownerDID,
+        String(key.suite),
+        String(key.version),
+        key.state
+    ]);
+}
+/** Every field of the wrapping a receiver writes, including the factor descriptors. */ export function credentialWrappingDigest(wrapping) {
+    return digestParts([
+        wrapping.wrappingID,
+        // An absent recipient digests as an empty part rather than being skipped:
+        // the parts are length-prefixed, and no DID is the empty string, so the two
+        // cases stay distinguishable without a marker of their own.
+        wrapping.recipientDID ?? '',
+        wrapping.iv,
+        wrapping.wrappedKey,
+        canonicalJSON(wrapping.factors)
+    ]);
+}
+/**
+ * Entries in `entryID` order, so the same set digests identically wherever it is
+ * assembled. `listEntries` order is the store's, and two devices need not agree
+ * on it.
+ *
+ * `hlc` contributes along with the ciphertext: the receiver writes it into the
+ * entry row, and an input the receiver stores that the signature does not cover
+ * is an unauthenticated write.
+ */ export function credentialEntriesDigest(entries) {
+    const ordered = [
+        ...entries
+    ].sort((left, right)=>left.entryID < right.entryID ? -1 : left.entryID > right.entryID ? 1 : 0);
+    return digestParts(ordered.flatMap((entry)=>[
+            entry.entryID,
+            entry.iv,
+            entry.ciphertext,
+            entry.hlc
+        ]));
+}
+/** One entry's digest is the one-element set's — the same framing, not a second one. */ export function credentialEntryDigest(entry) {
+    return credentialEntriesDigest([
+        entry
+    ]);
+}

package/lib/errors.d.ts

@@ -0,0 +1,169 @@
+import type { CredentialAuthorization } from './authority.js';
+/**
+ * A machine-readable name for a failure, stable across message rewording.
+ *
+ * A union rather than a loose string so that a new error class cannot be added
+ * without deciding what a caller is meant to match on. Messages are for people
+ * and change; these do not.
+ */
+export type CredentialErrorCode = 'CREDENTIAL_ERROR' | 'CREDENTIAL_FACTOR_UNAVAILABLE' | 'CREDENTIAL_FACTORS_INVALID' | 'CREDENTIAL_KEY_LOCKED' | 'CREDENTIAL_KEY_VERSION_MISMATCH' | 'CREDENTIAL_NOT_AUTHORIZED' | 'CREDENTIAL_NOT_FOUND' | 'CREDENTIAL_PIN_REJECTED' | 'CREDENTIAL_SECRET_REJECTED' | 'CREDENTIAL_SUPERSEDED_BRANCH' | 'CREDENTIAL_SUITE_UNSUPPORTED' | 'CREDENTIAL_TAMPERED' | 'CREDENTIAL_UNOPENABLE' | 'CREDENTIAL_WRAPPING_AMBIGUOUS';
+export type CredentialErrorOptions = ErrorOptions & {
+    code: CredentialErrorCode;
+};
+/**
+ * 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 declare class CredentialError extends Error {
+    #private;
+    constructor(message: string, options: CredentialErrorOptions);
+    get code(): CredentialErrorCode;
+}
+/** A wrapping needs a factor kind this device cannot supply. */
+export declare class NoAvailableFactor extends CredentialError {
+    #private;
+    constructor(kind: string);
+    get kind(): string;
+}
+/**
+ * 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 declare class InvalidCredentialFactors extends CredentialError {
+    constructor(reason: string);
+}
+/** A key names a ciphersuite this build does not implement. */
+export declare class UnsupportedCredentialSuite extends CredentialError {
+    #private;
+    constructor(suite: number);
+    get suite(): number;
+}
+/**
+ * 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 declare class CredentialTampered extends CredentialError {
+    constructor(message: string, options?: ErrorOptions);
+}
+/** An entry belongs to a branch superseded by the key's resolved winner. */
+export declare class CredentialSupersededBranch extends CredentialError {
+    #private;
+    constructor(entryID: string, entryBranchID: string, winnerBranchID: string);
+    get entryID(): string;
+    get entryBranchID(): string;
+    get winnerBranchID(): string;
+}
+/**
+ * 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 declare class CredentialSecretRejected extends CredentialError {
+    #private;
+    constructor(kinds: Array<string>, options?: ErrorOptions & {
+        keyID?: string;
+        code?: CredentialErrorCode;
+    });
+    /** The user-supplied factor kinds in the wrapping, any of which could be wrong. */
+    get kinds(): Array<string>;
+}
+/**
+ * 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 declare class CredentialPinRejected extends CredentialSecretRejected {
+    #private;
+    constructor(keyID: string, options: ErrorOptions & {
+        attemptsRemaining: number;
+        retryAfter: number;
+    });
+    /** Attempts left before a delay begins. */
+    get attemptsRemaining(): number;
+    /** Milliseconds until another attempt is accepted. Zero means now. */
+    get retryAfter(): number;
+}
+/**
+ * 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 declare class CredentialNotAuthorized extends CredentialError {
+    #private;
+    constructor(authorization: CredentialAuthorization, keyID: string);
+    get authorization(): CredentialAuthorization;
+}
+/** No key, wrapping or entry under that id. */
+export declare class CredentialNotFound extends CredentialError {
+    constructor(what: string, id: string);
+}
+/**
+ * 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 declare class AmbiguousCredentialWrapping extends CredentialError {
+    constructor(keyID: string, count: number);
+}
+/**
+ * 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 declare class CredentialKeyLocked extends CredentialError {
+    #private;
+    constructor(keyID: string, kinds: Array<string>);
+    get keyID(): string;
+}
+/**
+ * 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 declare class CredentialKeyVersionMismatch extends CredentialError {
+    constructor(entryID: string, entryVersion: number, keyVersion: number);
+}
+/**
+ * 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 declare class CredentialUnopenable extends CredentialError {
+    #private;
+    constructor(keyID: string, reason: string);
+    get keyID(): string;
+}