@serfab/cadre-core 1.16.0 → 1.18.0

package/dist/owner-key-export.js

@@ -0,0 +1,279 @@
+/**
+ * Owner-key export and import: the text (or QR code) a user keeps as a backup of an owner key or
+ * carries to another device (`docs/architecture.md` → Owner Keys → Exporting and importing an
+ * owner key). Whoever holds a plain export is an owner.
+ *
+ * - Plain: {@link OWNER_KEY_EXPORT_PREFIX}, then base64url of the canonical JSON
+ *   `{ key, label?, v: 1 }`, `key` being the 32-byte Ed25519 seed in base64url.
+ * - Locked: {@link LOCKED_OWNER_KEY_EXPORT_PREFIX}, then base64url of the canonical JSON
+ *   `{ kdf: { N, name: 'scrypt', p, r, salt }, nonce, sealed, v: 1 }`, `sealed` being the plain
+ *   JSON under XChaCha20-Poly1305 with the 32-byte key scrypt derives from the passphrase. The
+ *   scrypt parameters ride in the text, so a later default still reads an old export.
+ *
+ * No error carries key material. `@noble/hashes` and `@noble/ciphers` are pure JS and random
+ * bytes come from `crypto.getRandomValues`, so this loads on React Native and in the browser.
+ */
+import { xchacha20poly1305 } from '@noble/ciphers/chacha.js';
+import { scryptAsync } from '@noble/hashes/scrypt.js';
+import { randomBytes } from '@noble/hashes/utils.js';
+import { fromString as uint8ArrayFromString, toString as uint8ArrayToString } from 'uint8arrays';
+import { canonicalJson } from './canonical-json.js';
+import { CADRE_INVITATION_PREFIX, CADRE_JOIN_REQUEST_PREFIX, OWNER_GRANT_PREFIX, OWNER_KEY_EXPORT_STEM } from './cadre-join-request.js';
+import { NODE_CLAIM_PAYLOAD_PREFIX } from './node-claim-payload.js';
+import { ed25519PublicKeyFromPrivate, requireEd25519PrivateKeyB64 } from './ed25519-key.js';
+/** Version 1 of the plain export. */
+export const OWNER_KEY_EXPORT_PREFIX = `${OWNER_KEY_EXPORT_STEM}:1.`;
+/** Version 1 of the passphrase-locked export. */
+export const LOCKED_OWNER_KEY_EXPORT_PREFIX = `${OWNER_KEY_EXPORT_STEM}-locked:1.`;
+/** Longest label an owner key carries, the user's name for it ("phone", "paper backup"): in an export and on its `OwnerKey` row (the control schema's `LabelLength` check). */
+export const OWNER_KEY_MAX_LABEL = 64;
+/**
+ * The encoder's scrypt cost: about 140 ms and 64 MiB on Node 24 (x64, measured with
+ * `scryptAsync`).
+ * NOTE: unmeasured on Hermes; if a device run shows locking or unlocking is slow, lower N for the
+ * locked form or move the KDF to native.
+ */
+const DEFAULT_SCRYPT_COST = { N: 2 ** 16, r: 8, p: 1 };
+/**
+ * The most scrypt work the decoder runs, checked before deriving so a hostile file cannot keep a
+ * device busy for minutes: N at most 2^20 and r·p at most 8, sixteen times the default's work.
+ * At the cap scrypt takes about 2.5 s and 1 GiB on Node 24.
+ * NOTE: unmeasured on Hermes; if a device run shows the cap runs for minutes or exhausts memory,
+ * lower these two.
+ */
+const MAX_SCRYPT_N = 2 ** 20;
+const MAX_SCRYPT_R_TIMES_P = 8;
+/** noble's `maxmem` for {@link MAX_SCRYPT_N}: its default (1 GiB + 1 KiB) is below what the cap itself needs, `128·r·(N + p + 1)` bytes. */
+const SCRYPT_MAXMEM = 128 * MAX_SCRYPT_R_TIMES_P * (MAX_SCRYPT_N + MAX_SCRYPT_R_TIMES_P + 1);
+const SCRYPT_SALT_BYTES = 16;
+const MAX_SCRYPT_SALT_BYTES = 64;
+const XCHACHA_NONCE_BYTES = 24;
+const POLY1305_TAG_BYTES = 16;
+/** A sealed plain export is under 200 bytes; this bounds what a hostile file makes the decoder decrypt. */
+const MAX_SEALED_BYTES = 1024;
+/** Every refusal from this module. The message is for the user and never includes key material. */
+export class OwnerKeyExportError extends Error {
+    constructor(code, message, options) {
+        super(message, options);
+        this.name = 'OwnerKeyExportError';
+        this.code = code;
+    }
+}
+/**
+ * Encode an owner key as text, locked under `passphrase` when one is given.
+ *
+ * @throws {OwnerKeyExportError} `malformed` for a key that is not a 32-byte seed, an over-long
+ *   label or an empty passphrase.
+ */
+export async function encodeOwnerKeyExport(input) {
+    const plainJson = plainExportJson(input.privateKeyB64, input.label);
+    if (input.passphrase === undefined) {
+        return withPrefix(OWNER_KEY_EXPORT_PREFIX, plainJson);
+    }
+    return withPrefix(LOCKED_OWNER_KEY_EXPORT_PREFIX, await lockedExportJson(plainJson, input.passphrase));
+}
+/**
+ * Read owner-key text without a passphrase: a plain export's key, or `{ locked: true }` for a
+ * locked one whose envelope is well formed and whose scrypt cost is within the cap, so an app
+ * refuses a hostile file before asking for the passphrase.
+ *
+ * @throws {OwnerKeyExportError} `not-an-owner-key` (naming an invitation, an owner grant, a join
+ *   request or a join code), `malformed` or `cost-too-high`.
+ */
+export function decodeOwnerKeyExport(text) {
+    const trimmed = text.trim();
+    if (exportPrefix(trimmed) === LOCKED_OWNER_KEY_EXPORT_PREFIX) {
+        lockedEnvelope(decodeBody(trimmed, LOCKED_OWNER_KEY_EXPORT_PREFIX));
+        return { locked: true };
+    }
+    return { locked: false, ...exportContents(decodeBody(trimmed, OWNER_KEY_EXPORT_PREFIX)) };
+}
+/**
+ * Read owner-key text with its passphrase. A plain export is read as {@link decodeOwnerKeyExport}
+ * reads it, the passphrase unused.
+ *
+ * @throws {OwnerKeyExportError} as {@link decodeOwnerKeyExport}, and `wrong-passphrase` when the
+ *   passphrase does not open it or the sealed part, nonce or scrypt parameters were altered.
+ */
+export async function unlockOwnerKeyExport(text, passphrase) {
+    const trimmed = text.trim();
+    const prefix = exportPrefix(trimmed);
+    if (prefix === OWNER_KEY_EXPORT_PREFIX) {
+        return exportContents(decodeBody(trimmed, prefix));
+    }
+    const envelope = lockedEnvelope(decodeBody(trimmed, prefix));
+    const key = await deriveKey(passphrase, envelope, envelope.salt);
+    let plain;
+    try {
+        plain = xchacha20poly1305(key, envelope.nonce).decrypt(envelope.sealed);
+    }
+    catch (error) {
+        throw new OwnerKeyExportError('wrong-passphrase', 'The passphrase does not unlock this owner key, or the text was altered', { cause: error });
+    }
+    return exportContents(parseJsonObject(new TextDecoder().decode(plain)));
+}
+// ── Encoding ─────────────────────────────────────────────────────────────────
+function plainExportJson(privateKeyB64, label) {
+    const key = requireKey(privateKeyB64);
+    const trimmedLabel = label?.trim();
+    return canonicalJson({ key, label: trimmedLabel ? requireLabel(trimmedLabel) : undefined, v: 1 });
+}
+async function lockedExportJson(plainJson, passphrase) {
+    if (passphrase.length === 0) {
+        throw new OwnerKeyExportError('malformed', 'A passphrase must not be empty; leave it out for an unlocked export');
+    }
+    const salt = randomBytes(SCRYPT_SALT_BYTES);
+    const nonce = randomBytes(XCHACHA_NONCE_BYTES);
+    const key = await deriveKey(passphrase, DEFAULT_SCRYPT_COST, salt);
+    const sealed = xchacha20poly1305(key, nonce).encrypt(new TextEncoder().encode(plainJson));
+    return canonicalJson({
+        kdf: { ...DEFAULT_SCRYPT_COST, name: 'scrypt', salt: toBase64url(salt) },
+        nonce: toBase64url(nonce),
+        sealed: toBase64url(sealed),
+        v: 1,
+    });
+}
+function withPrefix(prefix, json) {
+    return `${prefix}${toBase64url(new TextEncoder().encode(json))}`;
+}
+/** scrypt's async form yields to the event loop every few milliseconds, so a phone's UI keeps drawing while it runs. */
+function deriveKey(passphrase, cost, salt) {
+    // NFKC, so one passphrase typed on keyboards that compose its characters differently derives one key.
+    const password = new TextEncoder().encode(passphrase.normalize('NFKC'));
+    return scryptAsync(password, salt, { N: cost.N, r: cost.r, p: cost.p, dkLen: 32, maxmem: SCRYPT_MAXMEM });
+}
+// ── Decoding ─────────────────────────────────────────────────────────────────
+/** Which of the two prefixes `text` starts with; refuses, by name where it can, anything else. */
+function exportPrefix(text) {
+    if (text.startsWith(LOCKED_OWNER_KEY_EXPORT_PREFIX))
+        return LOCKED_OWNER_KEY_EXPORT_PREFIX;
+    if (text.startsWith(OWNER_KEY_EXPORT_PREFIX))
+        return OWNER_KEY_EXPORT_PREFIX;
+    if (text.startsWith(OWNER_KEY_EXPORT_STEM)) {
+        throw new OwnerKeyExportError('malformed', 'This owner key was exported by a newer version of the app; update this app to import it');
+    }
+    throw new OwnerKeyExportError('not-an-owner-key', notAnOwnerKeyMessage(text));
+}
+/** No prefix of the text is echoed: whatever was pasted may be a key in some other form. */
+function notAnOwnerKeyMessage(text) {
+    if (text.startsWith(CADRE_INVITATION_PREFIX)) {
+        return 'This is a cadre invitation, not an owner key; paste it where the app asks for an invitation';
+    }
+    if (text.startsWith(OWNER_GRANT_PREFIX)) {
+        return 'This is an owner grant, not an owner key; paste it where the app asks for an owner grant';
+    }
+    if (text.startsWith(CADRE_JOIN_REQUEST_PREFIX)) {
+        return 'This is a join request, not an owner key; paste it into the app that manages your cadre';
+    }
+    if (text.startsWith(NODE_CLAIM_PAYLOAD_PREFIX)) {
+        return 'This is a machine\'s join code, not an owner key; scan it where the app adds a machine';
+    }
+    return `An owner key must start with "${OWNER_KEY_EXPORT_PREFIX}" or "${LOCKED_OWNER_KEY_EXPORT_PREFIX}"`;
+}
+function decodeBody(text, prefix) {
+    let json;
+    try {
+        json = new TextDecoder().decode(uint8ArrayFromString(text.slice(prefix.length), 'base64url'));
+    }
+    catch (error) {
+        throw new OwnerKeyExportError('malformed', 'An owner key export must carry base64url after its prefix', { cause: error });
+    }
+    return parseJsonObject(json);
+}
+/** A version-1 JSON object, the shape of both the export body and a locked export's sealed plaintext. */
+function parseJsonObject(json) {
+    let parsed;
+    try {
+        parsed = JSON.parse(json);
+    }
+    catch {
+        // No cause: JSON.parse's message can quote the input, which may hold the key.
+        throw new OwnerKeyExportError('malformed', 'An owner key export must carry JSON after its prefix');
+    }
+    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+        throw new OwnerKeyExportError('malformed', 'An owner key export must decode to a JSON object');
+    }
+    const record = parsed;
+    if (record.v !== 1) {
+        throw new OwnerKeyExportError('malformed', `An owner key export must be version 1 (this one says ${JSON.stringify(record.v)})`);
+    }
+    return record;
+}
+function exportContents(record) {
+    const { key, label } = record;
+    if (typeof key !== 'string') {
+        throw new OwnerKeyExportError('malformed', 'An owner key export must carry its key');
+    }
+    if (label !== undefined && (typeof label !== 'string' || label.trim().length === 0)) {
+        throw new OwnerKeyExportError('malformed', 'An owner key export\'s label must be non-empty text');
+    }
+    const privateKeyB64 = requireKey(key);
+    return {
+        privateKeyB64,
+        publicKey: ed25519PublicKeyFromPrivate(privateKeyB64),
+        ...(label === undefined ? {} : { label: requireLabel(label.trim()) }),
+    };
+}
+function lockedEnvelope(record) {
+    const { kdf, nonce, sealed } = record;
+    if (typeof kdf !== 'object' || kdf === null || Array.isArray(kdf)) {
+        throw new OwnerKeyExportError('malformed', 'A locked owner key must name its key derivation');
+    }
+    const { name, N, r, p, salt } = kdf;
+    if (name !== 'scrypt') {
+        throw new OwnerKeyExportError('malformed', `A locked owner key must use scrypt (this one names ${JSON.stringify(name)})`);
+    }
+    const cost = requireScryptCost(N, r, p);
+    return {
+        ...cost,
+        salt: requireBytes(salt, 'salt', 1, MAX_SCRYPT_SALT_BYTES),
+        nonce: requireBytes(nonce, 'nonce', XCHACHA_NONCE_BYTES, XCHACHA_NONCE_BYTES),
+        sealed: requireBytes(sealed, 'sealed key', POLY1305_TAG_BYTES, MAX_SEALED_BYTES),
+    };
+}
+function requireScryptCost(N, r, p) {
+    if (!isPositiveInteger(N) || N < 2 || (N & (N - 1)) !== 0 || !isPositiveInteger(r) || !isPositiveInteger(p)) {
+        throw new OwnerKeyExportError('malformed', 'A locked owner key\'s scrypt parameters must be positive integers, N a power of two');
+    }
+    if (N > MAX_SCRYPT_N || r * p > MAX_SCRYPT_R_TIMES_P) {
+        throw new OwnerKeyExportError('cost-too-high', `This locked owner key asks for more work to unlock than this app allows (scrypt N ${N}, r ${r}, p ${p})`);
+    }
+    return { N, r, p };
+}
+function isPositiveInteger(value) {
+    return typeof value === 'number' && Number.isSafeInteger(value) && value > 0;
+}
+function requireBytes(value, field, minBytes, maxBytes) {
+    let bytes;
+    if (typeof value === 'string') {
+        try {
+            bytes = uint8ArrayFromString(value, 'base64url');
+        }
+        catch (error) {
+            throw new OwnerKeyExportError('malformed', `A locked owner key's ${field} must be base64url`, { cause: error });
+        }
+    }
+    if (bytes === undefined || bytes.length < minBytes || bytes.length > maxBytes) {
+        throw new OwnerKeyExportError('malformed', `A locked owner key's ${field} must be ${minBytes === maxBytes ? minBytes : `${minBytes} to ${maxBytes}`} bytes of base64url`);
+    }
+    return bytes;
+}
+// ── Shared field rules ───────────────────────────────────────────────────────
+function requireKey(privateKeyB64) {
+    try {
+        return requireEd25519PrivateKeyB64(privateKeyB64, 'owner key');
+    }
+    catch (error) {
+        throw new OwnerKeyExportError('malformed', error instanceof Error ? error.message : 'The owner key must be a 32-byte Ed25519 private key', { cause: error });
+    }
+}
+function requireLabel(label) {
+    if (label.length > OWNER_KEY_MAX_LABEL) {
+        throw new OwnerKeyExportError('malformed', `An owner key's label must be at most ${OWNER_KEY_MAX_LABEL} characters (this one has ${label.length})`);
+    }
+    return label;
+}
+function toBase64url(bytes) {
+    return uint8ArrayToString(bytes, 'base64url');
+}
+//# sourceMappingURL=owner-key-export.js.map

package/dist/owner-key-export.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"owner-key-export.js","sourceRoot":"","sources":["../src/owner-key-export.ts"],"names":[],"mappings":"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"}

package/dist/owner-key-flows.d.ts

@@ -0,0 +1,55 @@
+/**
+ * The owner-key actions an app's owner-key screen offers, built from the owner-key slot
+ * (`owner-key-store.ts`) and the export text (`owner-key-export.ts`): export the device's own key,
+ * and import an exported key into the device's owner slot (`docs/architecture.md` → Owner Keys →
+ * Exporting and importing an owner key). One copy for the phone kit and the web app.
+ *
+ * Over `CadreNode`'s public surface only; pure-JS crypto, so it loads on React Native and in the
+ * browser.
+ */
+import type { CadreNode } from './cadre-node.js';
+import type { KeyStore } from './key-store.js';
+/** How an owner key is exported. */
+export interface OwnerKeyExportOptions {
+    /** The user's name for the key, carried in the export. Trimmed, at most 64 characters, blank meaning none. */
+    label?: string;
+    /** Locks the export; must not be empty. Absent: a plain export. */
+    passphrase?: string;
+}
+/** An owner key's export and the key it holds: {@link exportOwnerKey}'s answer. */
+export interface ExportedOwnerKey {
+    /** The exported key (base64url). */
+    publicKey: string;
+    /** The private key as export text. */
+    exportText: string;
+}
+/** {@link importOwnerKeyInto}'s answer. */
+export interface ImportedOwnerKey {
+    /** The imported key (base64url), now in the owner slot. */
+    publicKey: string;
+    /** The node now signs with it: the key is a live owner of the node's party. */
+    wired: boolean;
+}
+/**
+ * Export the key in `keyStore`'s owner slot, the device's own owner key, which is the key the
+ * kits' nodes sign with. The answer names the key, for a caller that shows the export under it.
+ *
+ * @throws when the slot is empty: a member device holds no owner key of its own to export.
+ * @throws {OwnerKeyExportError} `malformed` for an over-long label or an empty passphrase.
+ */
+export declare function exportOwnerKey(keyStore: KeyStore, options?: OwnerKeyExportOptions): Promise<ExportedOwnerKey>;
+/**
+ * Import owner-key text into `keyStore`'s owner slot and, given a running node, wire the key when
+ * it is a live owner of that node's party. Importing the key the slot already holds changes
+ * nothing; a different one is refused.
+ *
+ * A node that already signs with another key keeps it, since a node takes one owner signer; the
+ * imported key is stored, `wired` is false, and the next start wires it. The kits' nodes sign
+ * only with the slot's key, so there the case arises only for an embedder that wired another.
+ *
+ * @throws {OwnerKeyExportError} `passphrase-required` for locked text with no passphrase,
+ *   `wrong-passphrase`, or the decoder's refusals (`not-an-owner-key` names an invitation, join
+ *   request or join code).
+ * @throws {OwnerKeySlotOccupiedError} when the slot holds a different key.
+ */
+export declare function importOwnerKeyInto(keyStore: KeyStore, node: CadreNode | null, text: string, passphrase?: string): Promise<ImportedOwnerKey>;

package/dist/owner-key-flows.js

@@ -0,0 +1,60 @@
+import { ed25519PublicKeyFromPrivate } from './ed25519-key.js';
+import { decodeOwnerKeyExport, encodeOwnerKeyExport, OwnerKeyExportError, unlockOwnerKeyExport, } from './owner-key-export.js';
+import { importOwnerKey, readOwnerPrivateKey } from './owner-key-store.js';
+/**
+ * Export the key in `keyStore`'s owner slot, the device's own owner key, which is the key the
+ * kits' nodes sign with. The answer names the key, for a caller that shows the export under it.
+ *
+ * @throws when the slot is empty: a member device holds no owner key of its own to export.
+ * @throws {OwnerKeyExportError} `malformed` for an over-long label or an empty passphrase.
+ */
+export async function exportOwnerKey(keyStore, options = {}) {
+    const privateKeyB64 = await readOwnerPrivateKey(keyStore);
+    if (privateKeyB64 === undefined) {
+        throw new Error('This device holds no owner key of its own to export');
+    }
+    const exportText = await encodeOwnerKeyExport({ privateKeyB64, ...exportFields(options) });
+    return { publicKey: ed25519PublicKeyFromPrivate(privateKeyB64), exportText };
+}
+/**
+ * Import owner-key text into `keyStore`'s owner slot and, given a running node, wire the key when
+ * it is a live owner of that node's party. Importing the key the slot already holds changes
+ * nothing; a different one is refused.
+ *
+ * A node that already signs with another key keeps it, since a node takes one owner signer; the
+ * imported key is stored, `wired` is false, and the next start wires it. The kits' nodes sign
+ * only with the slot's key, so there the case arises only for an embedder that wired another.
+ *
+ * @throws {OwnerKeyExportError} `passphrase-required` for locked text with no passphrase,
+ *   `wrong-passphrase`, or the decoder's refusals (`not-an-owner-key` names an invitation, join
+ *   request or join code).
+ * @throws {OwnerKeySlotOccupiedError} when the slot holds a different key.
+ */
+export async function importOwnerKeyInto(keyStore, node, text, passphrase) {
+    const contents = await readOwnerKeyExport(text, passphrase);
+    const signer = await importOwnerKey(keyStore, contents.privateKeyB64);
+    return { publicKey: signer.publicKey, wired: node !== null && (await wireIfOwner(node, signer)) };
+}
+async function readOwnerKeyExport(text, passphrase) {
+    const decoded = decodeOwnerKeyExport(text);
+    if (!decoded.locked)
+        return decoded;
+    if (passphrase === undefined) {
+        throw new OwnerKeyExportError('passphrase-required', 'This owner key is locked with a passphrase; enter it to import the key');
+    }
+    return await unlockOwnerKeyExport(text, passphrase);
+}
+/** `CadreNode.wireOwnKeyIfOwner(signer)`, unless the node already signs with another key, which it keeps. */
+async function wireIfOwner(node, signer) {
+    const wired = node.getOwnerSigner();
+    if (wired !== null && wired.publicKey !== signer.publicKey)
+        return false;
+    return await node.wireOwnKeyIfOwner(signer);
+}
+function exportFields(options) {
+    return {
+        ...(options.label !== undefined && { label: options.label }),
+        ...(options.passphrase !== undefined && { passphrase: options.passphrase }),
+    };
+}
+//# sourceMappingURL=owner-key-flows.js.map

package/dist/owner-key-flows.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"owner-key-flows.js","sourceRoot":"","sources":["../src/owner-key-flows.ts"],"names":[],"mappings":"AAUA,OAAO,EAAE,2BAA2B,EAAE,MAAM,kBAAkB,CAAC;AAE/D,OAAO,EACN,oBAAoB,EACpB,oBAAoB,EACpB,mBAAmB,EACnB,oBAAoB,GAEpB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAAE,cAAc,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AA2B3E;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc,CAAC,QAAkB,EAAE,UAAiC,EAAE;IAC3F,MAAM,aAAa,GAAG,MAAM,mBAAmB,CAAC,QAAQ,CAAC,CAAC;IAC1D,IAAI,aAAa,KAAK,SAAS,EAAE,CAAC;QACjC,MAAM,IAAI,KAAK,CAAC,qDAAqD,CAAC,CAAC;IACxE,CAAC;IACD,MAAM,UAAU,GAAG,MAAM,oBAAoB,CAAC,EAAE,aAAa,EAAE,GAAG,YAAY,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;IAC3F,OAAO,EAAE,SAAS,EAAE,2BAA2B,CAAC,aAAa,CAAC,EAAE,UAAU,EAAE,CAAC;AAC9E,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,CAAC,KAAK,UAAU,kBAAkB,CACvC,QAAkB,EAClB,IAAsB,EACtB,IAAY,EACZ,UAAmB;IAEnB,MAAM,QAAQ,GAAG,MAAM,kBAAkB,CAAC,IAAI,EAAE,UAAU,CAAC,CAAC;IAC5D,MAAM,MAAM,GAAG,MAAM,cAAc,CAAC,QAAQ,EAAE,QAAQ,CAAC,aAAa,CAAC,CAAC;IACtE,OAAO,EAAE,SAAS,EAAE,MAAM,CAAC,SAAS,EAAE,KAAK,EAAE,IAAI,KAAK,IAAI,IAAI,CAAC,MAAM,WAAW,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC,EAAE,CAAC;AACnG,CAAC;AAED,KAAK,UAAU,kBAAkB,CAAC,IAAY,EAAE,UAA8B;IAC7E,MAAM,OAAO,GAAG,oBAAoB,CAAC,IAAI,CAAC,CAAC;IAC3C,IAAI,CAAC,OAAO,CAAC,MAAM;QAAE,OAAO,OAAO,CAAC;IACpC,IAAI,UAAU,KAAK,SAAS,EAAE,CAAC;QAC9B,MAAM,IAAI,mBAAmB,CAAC,qBAAqB,EAAE,wEAAwE,CAAC,CAAC;IAChI,CAAC;IACD,OAAO,MAAM,oBAAoB,CAAC,IAAI,EAAE,UAAU,CAAC,CAAC;AACrD,CAAC;AAED,6GAA6G;AAC7G,KAAK,UAAU,WAAW,CAAC,IAAe,EAAE,MAAmB;IAC9D,MAAM,KAAK,GAAG,IAAI,CAAC,cAAc,EAAE,CAAC;IACpC,IAAI,KAAK,KAAK,IAAI,IAAI,KAAK,CAAC,SAAS,KAAK,MAAM,CAAC,SAAS;QAAE,OAAO,KAAK,CAAC;IACzE,OAAO,MAAM,IAAI,CAAC,iBAAiB,CAAC,MAAM,CAAC,CAAC;AAC7C,CAAC;AAED,SAAS,YAAY,CAAC,OAA8B;IACnD,OAAO;QACN,GAAG,CAAC,OAAO,CAAC,KAAK,KAAK,SAAS,IAAI,EAAE,KAAK,EAAE,OAAO,CAAC,KAAK,EAAE,CAAC;QAC5D,GAAG,CAAC,OAAO,CAAC,UAAU,KAAK,SAAS,IAAI,EAAE,UAAU,EAAE,OAAO,CAAC,UAAU,EAAE,CAAC;KAC3E,CAAC;AACH,CAAC"}

package/dist/owner-key-store.d.ts

@@ -0,0 +1,31 @@
+import { type KeyId, type KeyStore } from './key-store.js';
+import { type OwnerSigner } from './owner-signer.js';
+/** A create or import found the owner slot already holding a key (a different one, for an import). Carries no key material. */
+export declare class OwnerKeySlotOccupiedError extends Error {
+    readonly keyId: KeyId;
+    constructor(keyId: KeyId, message: string);
+}
+/**
+ * Generate a fresh owner key and keep it in the slot.
+ *
+ * @throws {OwnerKeySlotOccupiedError} when the slot holds anything, unreadable bytes included.
+ */
+export declare function createOwnerKey(keyStore: KeyStore, keyId?: KeyId): Promise<OwnerSigner>;
+/**
+ * A signer over the key in the slot, or `undefined` when the slot is empty. Never generates one.
+ * A rejected `get` (e.g. `KeyStoreAccessError`) propagates, and bytes that are not an Ed25519
+ * private key throw: neither means the slot is empty.
+ */
+export declare function loadOwnerSigner(keyStore: KeyStore, keyId?: KeyId): Promise<OwnerSigner | undefined>;
+/**
+ * Keep an imported owner key (its 32-byte Ed25519 seed, base64url) in the slot. Importing the key
+ * the slot already holds changes nothing.
+ *
+ * @throws {OwnerKeySlotOccupiedError} when the slot holds anything else, unreadable bytes included.
+ */
+export declare function importOwnerKey(keyStore: KeyStore, privateKeyB64: string, keyId?: KeyId): Promise<OwnerSigner>;
+/**
+ * The slot's private key as a base64url Ed25519 seed, or `undefined` when the slot is empty. For
+ * exporting the key (`owner-key-export.ts`); everything else signs through {@link loadOwnerSigner}.
+ */
+export declare function readOwnerPrivateKey(keyStore: KeyStore, keyId?: KeyId): Promise<string | undefined>;

package/dist/owner-key-store.js

@@ -0,0 +1,81 @@
+/**
+ * The owner-key slot: an owner key kept in a {@link KeyStore} slot of its own, apart from the
+ * node's identity slot (`docs/architecture.md` → Owner Keys).
+ *
+ * Unlike the identity slot (`identity-key.ts`), an empty owner slot is never filled on read: an
+ * owner key exists because the user made or imported one. Nothing here overwrites a slot that
+ * holds anything, since the key in it is what the user's cadres list as an owner.
+ *
+ * The stored form is the identity slot's: the libp2p protobuf bytes of an Ed25519 private key.
+ * Dependency-free beyond `@libp2p/crypto`, so this module is safe in every entry graph.
+ *
+ * NOTE: each write checks the slot and then sets it, which a `KeyStore` cannot do atomically; two
+ * concurrent creates or imports into one slot can both pass the check and the later write wins.
+ * Callers run one owner-key action at a time; if one ever can race another, serialize them here.
+ */
+import { generateKeyPair, generateKeyPairFromSeed, privateKeyFromProtobuf, privateKeyToProtobuf } from '@libp2p/crypto/keys';
+import { equals as uint8ArrayEquals, fromString as uint8ArrayFromString } from 'uint8arrays';
+import { DEFAULT_OWNER_KEY_ID } from './key-store.js';
+import { ed25519KeyPairFromLibp2p, requireEd25519PrivateKeyB64 } from './ed25519-key.js';
+import { softwareOwnerSigner } from './owner-signer.js';
+/** A create or import found the owner slot already holding a key (a different one, for an import). Carries no key material. */
+export class OwnerKeySlotOccupiedError extends Error {
+    constructor(keyId, message) {
+        super(message);
+        this.name = 'OwnerKeySlotOccupiedError';
+        this.keyId = keyId;
+    }
+}
+/**
+ * Generate a fresh owner key and keep it in the slot.
+ *
+ * @throws {OwnerKeySlotOccupiedError} when the slot holds anything, unreadable bytes included.
+ */
+export async function createOwnerKey(keyStore, keyId = DEFAULT_OWNER_KEY_ID) {
+    if (await keyStore.get(keyId) !== undefined) {
+        throw new OwnerKeySlotOccupiedError(keyId, `The owner-key slot "${keyId}" already holds a key`);
+    }
+    const generated = await generateKeyPair('Ed25519');
+    await keyStore.set(keyId, privateKeyToProtobuf(generated));
+    return softwareOwnerSigner(ed25519KeyPairFromLibp2p(generated).privateKeyB64);
+}
+/**
+ * A signer over the key in the slot, or `undefined` when the slot is empty. Never generates one.
+ * A rejected `get` (e.g. `KeyStoreAccessError`) propagates, and bytes that are not an Ed25519
+ * private key throw: neither means the slot is empty.
+ */
+export async function loadOwnerSigner(keyStore, keyId = DEFAULT_OWNER_KEY_ID) {
+    const privateKeyB64 = await readOwnerPrivateKey(keyStore, keyId);
+    return privateKeyB64 === undefined ? undefined : softwareOwnerSigner(privateKeyB64);
+}
+/**
+ * Keep an imported owner key (its 32-byte Ed25519 seed, base64url) in the slot. Importing the key
+ * the slot already holds changes nothing.
+ *
+ * @throws {OwnerKeySlotOccupiedError} when the slot holds anything else, unreadable bytes included.
+ */
+export async function importOwnerKey(keyStore, privateKeyB64, keyId = DEFAULT_OWNER_KEY_ID) {
+    const imported = requireEd25519PrivateKeyB64(privateKeyB64, 'owner private key');
+    // The stored form is deterministic for a given seed, so equal bytes mean the same key.
+    const importedBytes = privateKeyToProtobuf(await generateKeyPairFromSeed('Ed25519', uint8ArrayFromString(imported, 'base64url')));
+    const stored = await keyStore.get(keyId);
+    if (stored === undefined) {
+        await keyStore.set(keyId, importedBytes);
+    }
+    else if (!uint8ArrayEquals(stored, importedBytes)) {
+        throw new OwnerKeySlotOccupiedError(keyId, `The owner-key slot "${keyId}" already holds a different key`);
+    }
+    return softwareOwnerSigner(imported);
+}
+/**
+ * The slot's private key as a base64url Ed25519 seed, or `undefined` when the slot is empty. For
+ * exporting the key (`owner-key-export.ts`); everything else signs through {@link loadOwnerSigner}.
+ */
+export async function readOwnerPrivateKey(keyStore, keyId = DEFAULT_OWNER_KEY_ID) {
+    const bytes = await keyStore.get(keyId);
+    if (bytes === undefined)
+        return undefined;
+    // A format conversion of the owner key's own stored bytes, not a derivation from the node identity.
+    return ed25519KeyPairFromLibp2p(privateKeyFromProtobuf(bytes)).privateKeyB64;
+}
+//# sourceMappingURL=owner-key-store.js.map

package/dist/owner-key-store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"owner-key-store.js","sourceRoot":"","sources":["../src/owner-key-store.ts"],"names":[],"mappings":"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"}

package/dist/owner-keys.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Owner keys as an app lists, adds and removes them (`CadreNode.listOwnerKeys`,
+ * `CadreNode.addOwner`, `CadreNode.planOwnerKeyRemoval`, `CadreNode.removeOwner`): the
+ * projection of the live `OwnerKey` rows an owner-key screen shows, the read-only plan behind a
+ * removal's confirmation step, the check that a requested re-vouch stays inside that plan, and
+ * the by-name refusals. Pure; the reads and writes themselves are `CadreNode`'s and
+ * `ControlDatabase`'s.
+ */
+import type { CadreOwnerKey, CadrePeerRow, OwnerGrantStatus, OwnerKeyAddRefusal, OwnerKeyDependents, OwnerKeyRemovalPlan, OwnerKeyRemovalRefusal, OwnerKeyRow, RemoveOwnerOptions } from './types.js';
+/**
+ * `CadreNode.addOwner` refused by name, before any write. `code` says which rule
+ * ({@link OwnerKeyAddRefusal}), for an app to switch on; the message is for a log.
+ */
+export declare class OwnerKeyAddRefusedError extends Error {
+    readonly code: OwnerKeyAddRefusal;
+    readonly key: string;
+    constructor(key: string, code: OwnerKeyAddRefusal);
+}
+/**
+ * `CadreNode.removeOwner` refused by name, before any write. `code` says which rule
+ * ({@link OwnerKeyRemovalRefusal}), for an app to switch on; the message is for a log.
+ */
+export declare class OwnerKeyRemovalRefusedError extends Error {
+    readonly code: OwnerKeyRemovalRefusal;
+    readonly key: string;
+    constructor(key: string, code: OwnerKeyRemovalRefusal);
+}
+/** An owner key as an approval prompt names it: `"label" (key)`, or the key alone when it has no label. */
+export declare function namedOwnerKey(key: string, label: string | null): string;
+/**
+ * One {@link CadreOwnerKey} per live row, in the rows' order. `heldKey` is the key of this
+ * node's owner signer, if one is wired; `anchor` is this node's trusted-owner anchor.
+ */
+export declare function describeOwnerKeys(rows: readonly OwnerKeyRow[], heldKey: string | null, anchor: ReadonlySet<string>): CadreOwnerKey[];
+/** What {@link planOwnerKeyRemoval} judges from: one node's live rows and its own standing. */
+export interface OwnerKeyRemovalPlanInput {
+    key: string;
+    /** Live `CadrePeer` rows (`ControlDatabase.queryCadrePeers`). */
+    rows: readonly CadrePeerRow[];
+    /** Live `OwnerKey` rows (`ControlDatabase.queryOwnerKeyRows`). */
+    owners: readonly OwnerKeyRow[];
+    /** Every owner grant with its standing (`ControlDatabase.listOwnerGrantStatuses`); the live ones the key issued are the plan's `grants`. */
+    grants: readonly OwnerGrantStatus[];
+    selfPeerId: string | null;
+    /** The key of this node's owner signer when it is an enrolled owner (`CadreNode.ownerSignerEnrolledIn`), or null when it cannot sign owner writes. */
+    selfOwnerKey: string | null;
+    /** This node's trusted-owner anchor, for the listed entry's `trusted`. */
+    anchor: ReadonlySet<string>;
+}
+/**
+ * The plan for removing owner key `key` from these rows. The refusals come first and by name: a
+ * node that cannot sign; a key with no live row; the only live owner key (`MinOneOwner`), ahead
+ * of `self` so a sole owner asking to remove its own key hears the rule no other owner could
+ * get past either; and this node's own key, since the schema's remove branch wants a signer
+ * other than the removed key. With this node enrolled, a different live key always leaves two
+ * owners in one read, so `last-owner` reaches only that case, and concurrent removals elsewhere
+ * leave the schema to decide.
+ *
+ * `dependents` are the rows the key vouched, which every reader judges against its anchor
+ * through `VouchOwner`: once the key is removed they stop passing the membership predicate on
+ * every machine unless re-vouched first. This node's own rows are not among them. Its own
+ * `CadrePeer` row is re-vouched unasked (`revouchesOwnRow`): left on the removed key, every other
+ * machine would drop the remover. Its own `OwnerKey` row is reported as `ownDependency`, since
+ * re-vouching it would mean signing its own removal.
+ *
+ * `grants` are the live owner grants the key issued: a redemption wants a live issuer, so they
+ * stop working with the removal. They are listed, not withdrawn (`removeOwner` leaves them: a
+ * tombstone over a grant that can no longer be redeemed would add nothing).
+ */
+export declare function planOwnerKeyRemoval(input: OwnerKeyRemovalPlanInput): OwnerKeyRemovalPlan;
+/**
+ * The re-vouch `CadreNode.removeOwner` makes: what the caller asked for, checked against the
+ * plan, plus this node's own row (`selfPeerId`, first) when `plan.revouchesOwnRow`. Every
+ * requested key and peer must be in `plan.dependents`, so a caller cannot re-vouch a row the
+ * removed key never vouched. Throws naming the offenders, before anything is written.
+ * Duplicates are dropped.
+ */
+export declare function revouchWithinPlan(plan: OwnerKeyRemovalPlan, revouch: RemoveOwnerOptions['revouch'], selfPeerId: string | null): OwnerKeyDependents;