@serfab/cadre-core 1.16.0 → 1.18.0

package/dist/owner-grant-protocol.js

@@ -0,0 +1,344 @@
+/**
+ * Owner grant redemption transport: `/sereus/owner-grant/1.0.0`.
+ *
+ * A holder of an owner grant (an owner-signed `OwnerGrant` row plus the private half of the
+ * grant keypair, see {@link OwnerGrantBundle}) dials ANY member machine the grant names and
+ * proves possession of the grant and of the key it wants seated; the member seats the row if
+ * it does not hold it yet and writes the holder's `OwnerKey` row through
+ * `ControlDatabase.redeemOwnerGrant`. No machine is admitted and no peer id is named: the
+ * holder's network identity has nothing to do with the key it seats, so unlike the invitation
+ * protocol there is no connecting-identity check — both signatures already bind the grant, the
+ * nonce and the key. The owner that minted the grant need not be online.
+ *
+ * The exchange shape — one frame each way, the member's hardening and admission of the
+ * holder, the holder's address-by-address dialing in passes — is `member-redemption.ts`'s,
+ * shared with the invitation protocol; this module supplies the grant's bundle, request,
+ * checks, writes and refusal codes. Stranger-facing by design, classed `stranger-open` in
+ * `control-protocol-guard.ts`; the handler's own trust decision is the two signatures.
+ */
+import debug from 'debug';
+import { toString as uint8ArrayToString, fromString as uint8ArrayFromString } from 'uint8arrays';
+import { sign } from '@optimystic/quereus-plugin-crypto';
+import { ownerGrantRedeemMessage, ownerGrantConsentMessage, OwnerGrantIssuerUnknownError, InvitationExhaustedError } from './control-database.js';
+import { verifyOwnerGrantRow, verifyOwnerGrantRedemption } from './peer-authorization.js';
+import { OWNER_KEY_MAX_LABEL } from './owner-key-export.js';
+import { CADRE_INVITATION_PREFIX, CADRE_JOIN_REQUEST_PREFIX, OWNER_GRANT_PREFIX, OWNER_KEY_EXPORT_STEM } from './cadre-join-request.js';
+import { MemberRedemptionHandler, constraintRefusal, dialRedemption, dialRedemptionInPasses, isBoundedString, isEd25519KeyB64, isNullableBoundedString, isNullableUseCap, rejection, writeFailureRefusal } from './member-redemption.js';
+const log = debug('sereus:cadre:owner-grant-proto');
+/** Protocol id for owner grant redemption (parallel to `/sereus/cadre-invite/1.0.0`). */
+export const OWNER_GRANT_PROTOCOL = '/sereus/owner-grant/1.0.0';
+/** What the dialer calls the credential in log lines, deadline labels and error text. */
+const LABEL = 'Owner grant';
+/** Most machines a grant bundle may name; the issuer caps its own list far below this. */
+const MAX_BUNDLE_MEMBERS = 64;
+/**
+ * Encode a bundle for out-of-band delivery: {@link OWNER_GRANT_PREFIX}, then base64url over
+ * JSON. The prefix lets an app tell a grant from an invitation, a join request or an owner key
+ * and name the mistake when one is pasted for the other.
+ */
+export function encodeOwnerGrant(bundle) {
+    return `${OWNER_GRANT_PREFIX}${uint8ArrayToString(new TextEncoder().encode(JSON.stringify(bundle)), 'base64url')}`;
+}
+/**
+ * Decode a bundle, refusing anything that is not a well-formed version-1
+ * {@link OwnerGrantBundle} behind {@link OWNER_GRANT_PREFIX}. Standalone, like
+ * `decodeCadreInvitation`, so a client without a node can decode one.
+ *
+ * @throws on an owner key, a cadre invitation or a join request, a string without the prefix
+ *   or that is not base64url JSON after it, or one that decodes to another shape or version.
+ */
+export function decodeOwnerGrant(encoded) {
+    const trimmed = encoded.trim();
+    if (trimmed.startsWith(OWNER_KEY_EXPORT_STEM)) {
+        throw new Error('This is an owner key, not an owner grant; it is private, so import it only where the app asks for an owner key');
+    }
+    if (trimmed.startsWith(CADRE_INVITATION_PREFIX)) {
+        throw new Error('This is a cadre invitation, not an owner grant; paste it where the app asks for an invitation');
+    }
+    if (trimmed.startsWith(CADRE_JOIN_REQUEST_PREFIX)) {
+        throw new Error('This is a join request, not an owner grant; paste it into the app that manages your cadre');
+    }
+    if (!trimmed.startsWith(OWNER_GRANT_PREFIX)) {
+        throw new Error(`Owner grant must start with "${OWNER_GRANT_PREFIX}" (this one starts with "${trimmed.slice(0, OWNER_GRANT_PREFIX.length)}")`);
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(new TextDecoder().decode(uint8ArrayFromString(trimmed.slice(OWNER_GRANT_PREFIX.length), 'base64url')));
+    }
+    catch (error) {
+        throw new Error('Owner grant does not decode as base64url JSON', { cause: error });
+    }
+    if (!isWellFormedOwnerGrantBundle(parsed)) {
+        throw new Error('Owner grant is malformed or of an unsupported version');
+    }
+    return parsed;
+}
+function isWellFormedOwnerGrantBundle(value) {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    const { v, partyId, grantPrivateKey, grant, ownerKeys, members } = value;
+    return v === 1
+        && isBoundedString(partyId)
+        && isEd25519KeyB64(grantPrivateKey)
+        && isWellFormedOwnerGrantRow(grant)
+        && Array.isArray(ownerKeys) && ownerKeys.length > 0 && ownerKeys.every((key) => isEd25519KeyB64(key))
+        && Array.isArray(members) && members.length <= MAX_BUNDLE_MEMBERS && members.every((addr) => isBoundedString(addr));
+}
+/** Is `value` an {@link OwnerGrantRow} with every column in its stored form and bounded? */
+export function isWellFormedOwnerGrantRow(value) {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    const row = value;
+    return isEd25519KeyB64(row.key)
+        && isNullableBoundedString(row.label, OWNER_KEY_MAX_LABEL)
+        && isNullableBoundedString(row.expiresAt)
+        && isNullableUseCap(row.totalUses)
+        && isBoundedString(row.stampId)
+        && isEd25519KeyB64(row.issuerKey)
+        && isBoundedString(row.issuerSig);
+}
+/** Which refusals are worth repeating at the next address — the one place that says so. */
+export const OWNER_GRANT_REJECTION_RETRYABLE = {
+    'issuer-unknown': true,
+    'grant-invalid': false,
+    'grant-spent': false,
+    'party-mismatch': false,
+    'busy': true,
+    'conflict': true,
+    'internal': true
+};
+/** Is `value` a code this build knows? Own keys only, so a peer's `'constructor'` does not pass. */
+export function isOwnerGrantRejectionCode(value) {
+    return typeof value === 'string' && Object.prototype.hasOwnProperty.call(OWNER_GRANT_REJECTION_RETRYABLE, value);
+}
+// ── Errors the holder sees ───────────────────────────────────────────────────
+/**
+ * A member answered and refused (on `CadreNode.redeemOwnerGrant`'s local path, the member is
+ * this node). `code` is `'unrecognized'` when the frame carried none this build knows, and such
+ * a refusal counts as retryable, as the invitation's does.
+ */
+export class OwnerGrantRejectedError extends Error {
+    /** Both arguments come straight off the wire, so neither is trusted to have its declared type. */
+    constructor(code, reason) {
+        const text = typeof reason === 'string' ? reason : 'no reason provided';
+        super(`Owner grant refused: ${text}`);
+        this.name = 'OwnerGrantRejectedError';
+        this.code = isOwnerGrantRejectionCode(code) ? code : 'unrecognized';
+        this.reason = text;
+        this.retryable = this.code === 'unrecognized' || OWNER_GRANT_REJECTION_RETRYABLE[this.code];
+    }
+}
+/** Every address the bundle names was tried and none accepted. Always retryable; `outcomes` says what each address did. */
+export class OwnerGrantUnreachableError extends Error {
+    constructor(outcomes) {
+        super(outcomes.length === 0
+            ? 'Owner grant names no dialable member'
+            : `Owner grant could not be redeemed at any of its ${outcomes.length} address(es): `
+                + outcomes.map((outcome) => `${outcome.addr}: ${outcome.error.message}`).join('; '));
+        this.outcomes = outcomes;
+        this.retryable = true;
+        this.name = 'OwnerGrantUnreachableError';
+    }
+}
+/**
+ * A member accepted but its reply does not check out: another party id, another grant key, or
+ * a row not signed by one of the pinned owner keys. Final, for the invitation's reason: such a
+ * machine is not a member of the cadre the grant names.
+ */
+export class OwnerGrantReplyInvalidError extends Error {
+    constructor(message) {
+        super(`Owner grant reply refused: ${message}`);
+        this.retryable = false;
+        this.name = 'OwnerGrantReplyInvalidError';
+    }
+}
+// ── Shape checks ─────────────────────────────────────────────────────────────
+function isWellFormedRedeemRequest(value) {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    const { v, partyId, grant, ownerKey, usageStampId, grantSig, ownerSig } = value;
+    return v === 1
+        && isBoundedString(partyId)
+        && isWellFormedOwnerGrantRow(grant)
+        && isEd25519KeyB64(ownerKey)
+        && isBoundedString(usageStampId)
+        && isBoundedString(grantSig)
+        && isBoundedString(ownerSig);
+}
+/** An acceptance frame's fields. Throws on a malformed one. */
+function decodeAccepted(reply) {
+    if (!isBoundedString(reply.partyId) || !isWellFormedOwnerGrantRow(reply.grant)) {
+        throw new Error('Owner grant acceptance is missing its party id or a well-formed row');
+    }
+    return { accepted: true, partyId: reply.partyId, grant: reply.grant, alreadyOwner: reply.alreadyOwner === true };
+}
+// ── Request construction (holder side) ───────────────────────────────────────
+/**
+ * Build and sign the request for `bundle`: the holder's `'redeem'` signature with the grant's
+ * private key (held in memory for the length of this call) and the seated key's `'consent'`
+ * signature through `signConsent`, the `sign` of an open owner approval on the signer that
+ * holds `ownerKey`; both over (grant key, `usageStampId`, `ownerKey`) for the grant's party. The
+ * same bytes the schema verifies at the member (`ownerGrantRedeemMessage` /
+ * `ownerGrantConsentMessage`), and the same request goes to every member and every pass.
+ */
+export async function signOwnerGrantRequest(bundle, ownerKey, signConsent, usageStampId) {
+    const fields = { grantKey: bundle.grant.key, usageStampId, seatedKey: ownerKey };
+    const grantSig = sign(ownerGrantRedeemMessage(bundle.partyId, fields), bundle.grantPrivateKey, 'ed25519', 'bytes', 'base64url', 'base64url');
+    const ownerSig = await signConsent(ownerGrantConsentMessage(bundle.partyId, fields));
+    return { v: 1, partyId: bundle.partyId, grant: bundle.grant, ownerKey, usageStampId, grantSig, ownerSig };
+}
+/**
+ * The holder's check on an acceptance: the same party, the same grant key, and a row signed by
+ * an issuer the holder pinned from the bundle. Throws {@link OwnerGrantReplyInvalidError} naming
+ * the first failure. Bounded as `verifyRedeemReply` is: it catches a wrong-party or wrong-row
+ * answer, not a forged member, which the holder's anchor settles once its store syncs.
+ */
+export function verifyOwnerGrantReply(reply, bundle, isTrustedIssuer) {
+    if (reply.partyId !== bundle.partyId) {
+        throw new OwnerGrantReplyInvalidError(`the member serves party ${reply.partyId}, the grant names ${bundle.partyId}`);
+    }
+    if (reply.grant.key !== bundle.grant.key) {
+        throw new OwnerGrantReplyInvalidError('the member answered for a different grant');
+    }
+    if (!isTrustedIssuer(reply.grant.issuerKey)) {
+        throw new OwnerGrantReplyInvalidError('the row the member holds is not issued by one of the grant\'s owner keys');
+    }
+    if (!verifyOwnerGrantRow(bundle.partyId, reply.grant)) {
+        throw new OwnerGrantReplyInvalidError('the row the member holds is not signed by its issuer');
+    }
+}
+/** Constraint names the schema refuses a redemption with, and the code each maps to. */
+const REDEEM_CONSTRAINT_CODES = [
+    [/CHECK constraint failed: Authorized\b/, 'grant-spent', 'The grant is expired, withdrawn, exhausted, or its issuer is no longer an owner'],
+    [/CHECK constraint failed: (GrantPossessed|OwnerConsented|SeatedExists)\b/, 'grant-invalid', 'The redemption does not satisfy the grant'],
+    [/CHECK constraint failed: NotRevoked\b/, 'grant-spent', 'The grant was withdrawn'],
+];
+/**
+ * Member side of the grant protocol (`MemberRedemptionHandler` has the shape): after the
+ * request's shape, it checks the party and both signatures — nothing about the connecting
+ * peer, whose identity is unrelated to the key it seats — then seats the row from the bundle
+ * when this member holds none and redeems. An issuer this member does not know as an owner is
+ * the one retryable refusal left: the holder tries the next address, which may hold the
+ * issuer's row.
+ */
+export class OwnerGrantHandler extends MemberRedemptionHandler {
+    constructor(options) {
+        super('Owner grant', OWNER_GRANT_PROTOCOL, options);
+        this.busyRefusal = rejection('busy', 'Too many concurrent redemptions');
+        this.internalRefusal = rejection('internal', 'Internal redemption error');
+        this.malformedRefusal = rejection('grant-invalid', 'Malformed redemption request');
+        this.store = options.store;
+    }
+    isWellFormedRequest(value) {
+        return isWellFormedRedeemRequest(value);
+    }
+    checkRequest(request) {
+        if (request.partyId !== this.partyId) {
+            return rejection('party-mismatch', 'This machine serves another cadre');
+        }
+        const fields = { grantKey: request.grant.key, usageStampId: request.usageStampId, seatedKey: request.ownerKey };
+        if (!verifyOwnerGrantRedemption(this.partyId, fields, request.grantSig, request.ownerSig)) {
+            return rejection('grant-invalid', 'The redemption signatures do not verify');
+        }
+        return null;
+    }
+    readHeld(request) {
+        return this.store.queryOwnerGrant(request.grant.key);
+    }
+    isLive(request, held) {
+        return this.store.isOwnerGrantLive(request.grant, held);
+    }
+    /** The two writes — the seat only when this member holds no row, and the redemption, carrying the held row — as `CadreInviteHandler.redeemAdmitted`. */
+    async redeemAdmitted(request, remotePeerId, held) {
+        if (held === null) {
+            const refused = await this.seat(request, remotePeerId);
+            if (refused)
+                return refused;
+        }
+        let alreadyOwner;
+        try {
+            const result = await this.store.redeemOwnerGrant({
+                grantKey: request.grant.key,
+                ...(held ? { held } : {}),
+                seatedKey: request.ownerKey,
+                usageStampId: request.usageStampId,
+                grantSig: request.grantSig,
+                ownerSig: request.ownerSig
+            });
+            alreadyOwner = result.alreadyOwner;
+            log('grant %s redeemed for %s by %s (alreadyOwner=%s)', request.grant.key, request.ownerKey, remotePeerId, alreadyOwner);
+        }
+        catch (error) {
+            if (error instanceof InvitationExhaustedError) {
+                return rejection('grant-spent', 'The grant has no uses left');
+            }
+            log('redeeming grant %s for %s failed: %o', request.grant.key, request.ownerKey, error);
+            return constraintRefusal(error, REDEEM_CONSTRAINT_CODES) ?? writeFailureRefusal(error);
+        }
+        // The row as held: read before the write, or the bundle's copy the seat inserted verbatim or found.
+        return { accepted: true, partyId: this.partyId, grant: held ?? request.grant, alreadyOwner };
+    }
+    /** Seat the bundle's copy of the row; a refusal answered by name, or null once it is held. */
+    async seat(request, remotePeerId) {
+        try {
+            await this.store.seatOwnerGrant(request.grant);
+            return null;
+        }
+        catch (error) {
+            if (error instanceof OwnerGrantIssuerUnknownError) {
+                return rejection('issuer-unknown', 'The grant\'s issuer is not known as an owner here');
+            }
+            log('seating grant %s from %s failed: %o', request.grant.key, remotePeerId, error);
+            return constraintRefusal(error, REDEEM_CONSTRAINT_CODES) ?? writeFailureRefusal(error);
+        }
+    }
+}
+/** The grant's half of the shared dial loop: its label, protocol, bundle, codec, checks and errors. */
+function grantRedemption(options) {
+    return {
+        label: LABEL,
+        protocolId: options.protocolId ?? OWNER_GRANT_PROTOCOL,
+        members: options.bundle.members,
+        request: options.request,
+        decodeAccepted,
+        refusal: (code, reason) => new OwnerGrantRejectedError(code, reason),
+        verifyAccepted: (reply) => verifyOwnerGrantReply(reply, options.bundle, options.isTrustedIssuer),
+        unreachable: (outcomes) => new OwnerGrantUnreachableError(outcomes),
+        ...(options.linkRoundTripMs !== undefined ? { linkRoundTripMs: options.linkRoundTripMs } : {}),
+        ...(options.addressBudgetMs !== undefined ? { addressBudgetMs: options.addressBudgetMs } : {}),
+        ...(options.signal ? { signal: options.signal } : {}),
+    };
+}
+/**
+ * Holder side: try the bundle's addresses one at a time and stop at the first acceptance or
+ * the first final refusal (`dialRedemption` in `member-redemption.ts`). Every address gets the
+ * SAME request, with one `usageStampId`: `OwnerGrantUsage` is keyed by it, so a member the
+ * holder gave up on that was still committing cannot spend a second use, and a retry after a
+ * dropped reply is answered `alreadyOwner`.
+ *
+ * @throws {OwnerGrantRejectedError} on a final refusal (its `retryable` is false).
+ * @throws {OwnerGrantReplyInvalidError} on an acceptance that fails {@link verifyOwnerGrantReply}.
+ * @throws {OwnerGrantUnreachableError} when every address was tried and none accepted.
+ * @throws the reason of `options.signal` once it aborts.
+ */
+export function redeemOwnerGrantAtMembers(node, options) {
+    return dialRedemption(node, grantRedemption(options));
+}
+/**
+ * Holder side, in passes (`dialRedemptionInPasses` in `member-redemption.ts`): one
+ * {@link redeemOwnerGrantAtMembers} pass, or, with `waitForMember`, as many as it takes,
+ * pausing between them and never past the grant's expiry, which by this holder's clock is
+ * thrown as the `grant-spent` refusal a member would give. A backup grant has no expiry, so a
+ * wait on one ends only by acceptance, a final refusal, the signal or the node stopping.
+ */
+export function redeemOwnerGrantInPasses(node, options) {
+    const passes = {
+        ...grantRedemption(options),
+        waitForMember: options.waitForMember,
+        expiresAt: options.bundle.grant.expiresAt,
+        expired: () => new OwnerGrantRejectedError('grant-spent', 'the grant expired before a member accepted it'),
+        ...(options.onProgress ? { onProgress: options.onProgress } : {}),
+    };
+    return dialRedemptionInPasses(node, passes);
+}
+//# sourceMappingURL=owner-grant-protocol.js.map

package/dist/owner-grant-protocol.js.map

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

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

@@ -0,0 +1,70 @@
+/** Version 1 of the plain export. */
+export declare const OWNER_KEY_EXPORT_PREFIX = "sereus-owner-key:1.";
+/** Version 1 of the passphrase-locked export. */
+export declare const LOCKED_OWNER_KEY_EXPORT_PREFIX = "sereus-owner-key-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 declare const OWNER_KEY_MAX_LABEL = 64;
+export type OwnerKeyExportErrorCode = 
+/** Owner-key text whose body does not decode, or a version this build does not read. */
+'malformed'
+/** The passphrase does not open a locked export, or the locked text was altered. */
+ | 'wrong-passphrase'
+/** A locked export given with no passphrase (`importOwnerKeyInto` in `owner-key-flows.ts`). */
+ | 'passphrase-required'
+/** Not owner-key text; the message names an invitation, an owner grant, a join request or a join code. */
+ | 'not-an-owner-key'
+/** A locked export asks for more scrypt work than {@link MAX_SCRYPT_N} and {@link MAX_SCRYPT_R_TIMES_P} allow. */
+ | 'cost-too-high';
+/** Every refusal from this module. The message is for the user and never includes key material. */
+export declare class OwnerKeyExportError extends Error {
+    readonly code: OwnerKeyExportErrorCode;
+    constructor(code: OwnerKeyExportErrorCode, message: string, options?: {
+        cause?: unknown;
+    });
+}
+/** What an export holds once read. */
+export interface OwnerKeyExportContents {
+    /** The 32-byte Ed25519 seed, base64url: the input to `importOwnerKey`. */
+    privateKeyB64: string;
+    /** The matching public key, base64url: the `OwnerKey.Key` it signs for. */
+    publicKey: string;
+    label?: string;
+}
+/** {@link decodeOwnerKeyExport}'s answer: the key, or word that a passphrase is needed ({@link unlockOwnerKeyExport}). */
+export type DecodedOwnerKeyExport = ({
+    locked: false;
+} & OwnerKeyExportContents) | {
+    locked: true;
+};
+export interface OwnerKeyExportInput {
+    /** The 32-byte Ed25519 seed, base64url (`readOwnerPrivateKey`). */
+    privateKeyB64: string;
+    /** Trimmed; at most {@link OWNER_KEY_MAX_LABEL} characters; a blank one is left out. */
+    label?: string;
+    /** Locks the export when present; must not be empty. */
+    passphrase?: string;
+}
+/**
+ * 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 declare function encodeOwnerKeyExport(input: OwnerKeyExportInput): Promise<string>;
+/**
+ * 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 declare function decodeOwnerKeyExport(text: string): DecodedOwnerKeyExport;
+/**
+ * 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 declare function unlockOwnerKeyExport(text: string, passphrase: string): Promise<OwnerKeyExportContents>;