@kubun/credential 0.13.0

package/lib/suite.js

@@ -0,0 +1,317 @@
+import { deriveSharedSecretAsync } from '@kokuin/jwe';
+import { gcm } from '@noble/ciphers/aes.js';
+import { argon2idAsync } from '@noble/hashes/argon2.js';
+import { hkdf } from '@noble/hashes/hkdf.js';
+import { sha256 } from '@noble/hashes/sha2.js';
+import { concatBytes } from '@noble/hashes/utils.js';
+import { canonicalStringify, fromB64, fromUTF, toB64 } from '@sozai/codec';
+import { CredentialSecretRejected, CredentialTampered, InvalidCredentialFactors, NoAvailableFactor, UnsupportedCredentialSuite } from './errors.js';
+/** X25519 / HKDF-SHA256 / Argon2id / A256GCM. */ export const SUITE_KUBUN_CRED_1 = 1;
+const IV_LENGTH = 12;
+const CONTENT_KEY_LENGTH = 32;
+const FACTOR_SECRET_LENGTH = 32;
+const SALT_LENGTH = 16;
+const WRAP_INFO_PREFIX = 'kubun/credential-wrap/v1';
+const ARGON2_COST_LIMITS = {
+    m: {
+        min: 8,
+        max: 262_144
+    },
+    t: {
+        min: 1,
+        max: 10
+    },
+    p: {
+        min: 1,
+        max: 16
+    }
+};
+/**
+ * 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 const DEFAULT_ARGON2_COST = {
+    m: 19456,
+    t: 2,
+    p: 1
+};
+function invalidArgon2Cost(cost) {
+    for (const name of [
+        'm',
+        't',
+        'p'
+    ]){
+        const value = cost[name];
+        const limits = ARGON2_COST_LIMITS[name];
+        if (!Number.isSafeInteger(value) || value < limits.min || value > limits.max) {
+            return `${name} must be an integer from ${limits.min} through ${limits.max}`;
+        }
+    }
+    return null;
+}
+/**
+ * The wrapping's key-encryption key.
+ *
+ * `salt` is the wrapping id, so two wrappings of the same content key under the
+ * same secrets still derive different KEKs. `info` binds the suite, key and
+ * version, which is what stops a wrapping at version N opening ciphertext at
+ * N+1 — a rotation's whole point.
+ */ function deriveKEK(secrets, wrappingID, suiteID, keyID, keyVersion) {
+    const info = fromUTF(`${WRAP_INFO_PREFIX}:${suiteID}:${keyID}:${keyVersion}`);
+    return hkdf(sha256, concatBytes(...secrets), fromUTF(wrappingID), info, CONTENT_KEY_LENGTH);
+}
+/**
+ * The wrapping's additional authenticated data: the factor descriptors, in
+ * order, canonically serialized.
+ *
+ * Order is load-bearing twice over — the KEK concatenates the secrets in this
+ * order, and the AAD covers it — so a reordered list fails the tag rather than
+ * deriving a different key and failing indistinguishably from a wrong secret.
+ */ function wrappingAAD(descriptors) {
+    return fromUTF(canonicalStringify(descriptors));
+}
+/** Binds an entry's ciphertext to the exact key, version and entry it was written for. */ function entryAAD(suiteID, keyID, keyVersion, entryID) {
+    return fromUTF(`${suiteID}:${keyID}:${keyVersion}:${entryID}`);
+}
+/**
+ * The ECDH output is raw, not uniformly random. It is safe here only because
+ * `deriveKEK` runs every factor secret through HKDF with its own domain
+ * separation — a caller consuming this as a key directly would not be.
+ */ async function didFactorSecretForSender(recipientDID, methods) {
+    const { sharedSecret, ephemeralPublicKey } = await deriveSharedSecretAsync(recipientDID, {
+        methods: methods ?? []
+    });
+    return {
+        secret: sharedSecret,
+        params: {
+            recipient: recipientDID,
+            epk: toB64(ephemeralPublicKey)
+        }
+    };
+}
+/**
+ * The KDF runs here rather than in the manager.
+ *
+ * A caller deriving the secret itself would have to read the descriptor's salt
+ * and cost, which makes the suite's `passphraseKDF` a property nothing enforces:
+ * a later scrypt suite would silently be fed Argon2 output.
+ */ async function secretFactorForSender(runtime, input, cost) {
+    const invalid = invalidArgon2Cost(cost);
+    if (invalid != null) {
+        throw new InvalidCredentialFactors(`invalid Argon2 cost: ${invalid}`);
+    }
+    const salt = runtime.getRandomValues(new Uint8Array(SALT_LENGTH));
+    const secret = await argon2idAsync(input, salt, {
+        ...cost,
+        dkLen: FACTOR_SECRET_LENGTH
+    });
+    return {
+        secret,
+        params: {
+            salt: toB64(salt),
+            ...cost
+        }
+    };
+}
+async function secretFactorForRecipient(kind, input, params) {
+    if (input == null) {
+        throw new NoAvailableFactor(kind);
+    }
+    const { salt, m, t, p } = params;
+    if (typeof salt !== 'string' || typeof m !== 'number' || typeof t !== 'number' || typeof p !== 'number') {
+        throw new CredentialTampered(`${kind} factor descriptor carries no usable Argon2 parameters`);
+    }
+    const invalid = invalidArgon2Cost({
+        m,
+        t,
+        p
+    });
+    if (invalid != null) {
+        throw new CredentialTampered(`${kind} factor descriptor has invalid Argon2 cost: ${invalid}`);
+    }
+    let decodedSalt;
+    try {
+        decodedSalt = fromB64(salt);
+    } catch (cause) {
+        throw new CredentialTampered(`${kind} factor descriptor carries an invalid Argon2 salt`, {
+            cause
+        });
+    }
+    if (decodedSalt.length !== SALT_LENGTH) {
+        throw new CredentialTampered(`${kind} factor descriptor Argon2 salt must be ${SALT_LENGTH} bytes`);
+    }
+    return await argon2idAsync(input, decodedSalt, {
+        m,
+        t,
+        p,
+        dkLen: FACTOR_SECRET_LENGTH
+    });
+}
+/**
+ * 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 function validateFactorList(kinds) {
+    // Zero factors is not a weaker AND, it is no AND: `deriveKEK` runs over no
+    // secrets at all, so the wrapping opens for anyone holding the row.
+    if (kinds.length === 0) {
+        throw new InvalidCredentialFactors('a wrapping needs at least one factor');
+    }
+    const seen = new Set();
+    for (const kind of kinds){
+        if (kind === 'did') {
+            continue;
+        }
+        if (seen.has(kind)) {
+            throw new InvalidCredentialFactors(`duplicate "${kind}" factor`);
+        }
+        seen.add(kind);
+    }
+    // A pin is confirmation-bearing, not entropy-bearing: four digits are
+    // grindable by anyone holding the ciphertext. It is only worth anything
+    // chained to a key that device possession supplies, and a passphrase does not
+    // substitute — the threat model is the borrowed unlocked device, not the
+    // attacker with the database.
+    if (seen.has('pin') && !kinds.includes('did')) {
+        throw new InvalidCredentialFactors('a "pin" factor requires a "did" factor in the same wrapping');
+    }
+}
+async function didFactorSecretForRecipient(identity, params) {
+    if (identity == null) {
+        throw new NoAvailableFactor('did');
+    }
+    const epk = params.epk;
+    if (typeof epk !== 'string') {
+        throw new CredentialTampered('did factor descriptor carries no epk');
+    }
+    // No `kid`: the sender always resolves the first published keyAgreement key, and
+    // on a multi-KEM identity another one silently recovers different bytes.
+    return await identity.agreeKey(fromB64(epk));
+}
+const suite1 = {
+    id: SUITE_KUBUN_CRED_1,
+    name: 'KUBUN_CRED_1',
+    generateContentKey (runtime) {
+        return runtime.getRandomValues(new Uint8Array(CONTENT_KEY_LENGTH));
+    },
+    async wrap (params) {
+        validateFactorList(params.factors.map((factor)=>factor.kind));
+        const secrets = [];
+        const descriptors = [];
+        for (const factor of params.factors){
+            switch(factor.kind){
+                case 'did':
+                    {
+                        const { secret, params: factorParams } = await didFactorSecretForSender(factor.recipientDID, params.methods);
+                        secrets.push(secret);
+                        descriptors.push({
+                            kind: 'did',
+                            params: factorParams
+                        });
+                        break;
+                    }
+                case 'passphrase':
+                case 'pin':
+                    {
+                        const { secret, params: factorParams } = await secretFactorForSender(params.runtime, factor.input, factor.cost ?? DEFAULT_ARGON2_COST);
+                        secrets.push(secret);
+                        descriptors.push({
+                            kind: factor.kind,
+                            params: factorParams
+                        });
+                        break;
+                    }
+            }
+        }
+        const kek = deriveKEK(secrets, params.wrappingID, SUITE_KUBUN_CRED_1, params.keyID, params.keyVersion);
+        const iv = params.runtime.getRandomValues(new Uint8Array(IV_LENGTH));
+        return {
+            descriptors,
+            iv,
+            wrappedKey: gcm(kek, iv, wrappingAAD(descriptors)).encrypt(params.contentKey)
+        };
+    },
+    async unwrap (params) {
+        // Validated on open too, not only on create: wrappings arrive off the wire
+        // (`credential:key-grant`), and a pin-only wrapping is openable by anyone who
+        // guesses four digits, a factorless one by anyone at all. A wrapping this
+        // build refuses to make is not one it agrees to open.
+        validateFactorList(params.descriptors.map((descriptor)=>descriptor.kind));
+        const secrets = [];
+        const userSuppliedKinds = [];
+        for (const descriptor of params.descriptors){
+            switch(descriptor.kind){
+                case 'did':
+                    secrets.push(await didFactorSecretForRecipient(params.identity, descriptor.params));
+                    break;
+                case 'passphrase':
+                case 'pin':
+                    secrets.push(await secretFactorForRecipient(descriptor.kind, params.inputs?.[descriptor.kind], descriptor.params));
+                    userSuppliedKinds.push(descriptor.kind);
+                    break;
+                default:
+                    throw new NoAvailableFactor(descriptor.kind);
+            }
+        }
+        const kek = deriveKEK(secrets, params.wrappingID, SUITE_KUBUN_CRED_1, params.keyID, params.keyVersion);
+        try {
+            return gcm(kek, params.iv, wrappingAAD(params.descriptors)).decrypt(params.wrappedKey);
+        } catch (cause) {
+            // One tag failure is everything that is observable here, so which error
+            // this is amounts to a policy about who could have been wrong. With a
+            // user-supplied factor in the list the secret is the likely cause and the
+            // caller needs a retry path; with none, nothing the user typed could have
+            // been wrong and the remaining causes are all tampering.
+            if (userSuppliedKinds.length > 0) {
+                throw new CredentialSecretRejected(userSuppliedKinds, {
+                    cause,
+                    keyID: params.keyID
+                });
+            }
+            throw new CredentialTampered('credential wrapping failed authentication: its descriptors or ciphertext were altered, or it belongs to another key', {
+                cause
+            });
+        }
+    },
+    encryptEntry (params) {
+        const iv = params.runtime.getRandomValues(new Uint8Array(IV_LENGTH));
+        const aad = entryAAD(SUITE_KUBUN_CRED_1, params.keyID, params.keyVersion, params.entryID);
+        return {
+            iv,
+            ciphertext: gcm(params.contentKey, iv, aad).encrypt(params.plaintext)
+        };
+    },
+    decryptEntry (params) {
+        const aad = entryAAD(SUITE_KUBUN_CRED_1, params.keyID, params.keyVersion, params.entryID);
+        try {
+            return gcm(params.contentKey, params.iv, aad).decrypt(params.ciphertext);
+        } catch (cause) {
+            throw new CredentialTampered('credential entry failed authentication: it was altered, or is being read under the wrong key version', {
+                cause
+            });
+        }
+    }
+};
+const SUITES = new Map([
+    [
+        SUITE_KUBUN_CRED_1,
+        suite1
+    ]
+]);
+/** The suite a key names, or `UnsupportedCredentialSuite` — never a silent skip. */ export function getSuite(id) {
+    const suite = SUITES.get(id);
+    if (suite == null) {
+        throw new UnsupportedCredentialSuite(id);
+    }
+    return suite;
+}
+export function isSupportedSuite(id) {
+    return SUITES.has(id);
+}

package/lib/vocabulary.d.ts

@@ -0,0 +1,16 @@
+/**
+ * The capability action a device presents to administer (grant/rotate/revoke/
+ * factor-change) a controller-owned credential on its owner's behalf. It rides
+ * the same `checkCapability` matcher documents use — an action is matched by
+ * segment, so a `credential/*` grant covers it, exactly as `document/*` covers
+ * `document/write`.
+ */
+export declare const CREDENTIAL_ADMINISTER_ACTION = "credential/administer";
+/**
+ * The user-wide capability resource for a controller's credentials, mirroring
+ * `urn:kubun:user:<owner>` for documents: one delegation covers all of a
+ * controller's credentials rather than naming each key. The DID is normalized so
+ * the resource is an equality key — the same reason `owner_did` is normalized and
+ * a wrapping's recipient is not.
+ */
+export declare function credentialUserResource(controllerDID: string): string;

package/lib/vocabulary.js

@@ -0,0 +1,17 @@
+import { normalizeDID } from '@kokuin/token';
+/**
+ * The capability action a device presents to administer (grant/rotate/revoke/
+ * factor-change) a controller-owned credential on its owner's behalf. It rides
+ * the same `checkCapability` matcher documents use — an action is matched by
+ * segment, so a `credential/*` grant covers it, exactly as `document/*` covers
+ * `document/write`.
+ */ export const CREDENTIAL_ADMINISTER_ACTION = 'credential/administer';
+/**
+ * The user-wide capability resource for a controller's credentials, mirroring
+ * `urn:kubun:user:<owner>` for documents: one delegation covers all of a
+ * controller's credentials rather than naming each key. The DID is normalized so
+ * the resource is an equality key — the same reason `owner_did` is normalized and
+ * a wrapping's recipient is not.
+ */ export function credentialUserResource(controllerDID) {
+    return `urn:kubun:credential:user:${normalizeDID(controllerDID)}`;
+}

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@kubun/credential",
+  "version": "0.13.0",
+  "keywords": [],
+  "license": "see LICENSE.md",
+  "sideEffects": false,
+  "type": "module",
+  "exports": {
+    ".": "./lib/index.js"
+  },
+  "main": "lib/index.js",
+  "types": "lib/index.d.ts",
+  "files": [
+    "lib/*",
+    "LICENSE.md"
+  ],
+  "dependencies": {
+    "@kokuin/jwe": "^0.1.0",
+    "@kokuin/token": "^0.5.0",
+    "@noble/ciphers": "^2.3.0",
+    "@noble/hashes": "^2.3.0",
+    "@sozai/codec": "^0.4.0",
+    "@sozai/runtime": "^0.1.0",
+    "@kubun/hlc": "^0.13.0",
+    "@kubun/store-credential": "^0.13.0",
+    "@kubun/id": "^0.13.0"
+  },
+  "devDependencies": {
+    "@kubun/db-better-sqlite": "^0.13.0",
+    "@kubun/db": "^0.13.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "pnpm run build:clean && pnpm run build:js && pnpm run build:types",
+    "build:clean": "del lib",
+    "build:js": "swc src -d ./lib --config-file ../../node_modules/@kigu/dev/swc.json --strip-leading-paths",
+    "build:types": "tsc --emitDeclarationOnly --skipLibCheck",
+    "build:types:ci": "tsc --emitDeclarationOnly --declarationMap false",
+    "test": "pnpm run test:types && pnpm run test:unit",
+    "test:types": "tsc --noEmit -p tsconfig.test.json",
+    "test:unit": "vitest run"
+  }
+}