@a-company/gnomon 0.0.0-stage → 8.0.2

package/dist/signer-CQ3Bpe7G.d.ts

@@ -0,0 +1,158 @@
+import { KeyObject } from 'node:crypto';
+
+/**
+ * @symbol #kernel-log
+ *
+ * #kernel-log (spec §3.1 key classes + signature domains, §3.2 "Signatures and
+ * anchors") — the `Signer` seam and the key ring the verifier uses.
+ *
+ * THE SEAM. Every signature the log writes goes through `Signer.sign(domain,
+ * message)`. The signer, not the caller, prepends the domain, so a signature
+ * made for one purpose can never verify for another (domain separation):
+ *
+ *   preimage = utf8(<domain> + "\n" + <message>)
+ *
+ * with the §3.1 domains `gnomon:event-sig:v1`, `gnomon:row-sig:v1`,
+ * `gnomon:approve:v1`, `gnomon:approve-voice:v1`, `gnomon:auth:v1` and
+ * `gnomon:brief:v1`. For an event, `message` is the event's tagged hash
+ * (`sha256:<hex>`), so the signature commits to the whole envelope.
+ *
+ * Each key class may sign only its own domains (§3.1): the kernel key signs
+ * events, `hello` serverSig (`gnomon:auth-server:v2`, M1.4 — never the client
+ * `gnomon:auth:v1` domain, so the kernel is no signing oracle for client
+ * transcripts) and briefs; the root key signs rows
+ * (registry, grants, config, install); the approvals key signs decisions.
+ *
+ * PR-4 ships ONE implementation: `SoftwareEd25519Signer`, the kernel key held
+ * in kernel memory. In production the key material comes from the OS keystore
+ * item `gnomon-kernel-key` via the signed helper (§3.1); until probes P04
+ * (Secure Enclave / helper) and P02 land, a caller hands the PEM in. The root
+ * and approvals keys are HARDWARE P-256 and never software (§3.1 failure
+ * modes: "never a software fallback, never a file") — their signers plug in
+ * behind this same interface after P04/P02. The key ring already VERIFIES
+ * `gkey-p256:v1` signatures (ECDSA P-256 / SHA-256, IEEE-P1363 encoding) so
+ * those rows verify the day they appear.
+ *
+ * The interface is synchronous because the kernel key lives in kernel memory
+ * (§3.1 "loaded into kernel memory at daemon start") and append runs inside a
+ * write transaction. A hardware signer is asynchronous (helper XPC); it will
+ * get an async append path that serializes on the chain tip — deferred with
+ * the hardware signers.
+ */
+
+/** The §3.1 signature domains (the prefix before the first `\n`). */
+declare const SIGNATURE_DOMAINS: {
+    readonly event: "gnomon:event-sig:v1";
+    readonly row: "gnomon:row-sig:v1";
+    readonly approve: "gnomon:approve:v1";
+    readonly approveVoice: "gnomon:approve-voice:v1";
+    /** The three auth domains come FROM the contracts constants (P8-D93 round 3): one definition, in clientApiId. */
+    readonly auth: "gnomon:auth:v1";
+    /** #socket serverSig (§4.9): `gnomon:auth-server:v2\n` + contracts authServerMessage (nonce, clientNonce, endpointPath, negotiated hello; v2 since P8-D93), kernel key only. */
+    readonly authServer: "gnomon:auth-server:v2";
+    /** Read-token proof of possession (§4.9, P8-D89a): the token's own Ed25519 key only. */
+    readonly authToken: "gnomon:auth-token:v1";
+    readonly brief: "gnomon:brief:v1";
+    /**
+     * #approval-broker (M1.6): the kernel key signs `card.actions[]` and the
+     * presence-prompt record (§3.1 kernel key "Signs:"). The spec names no
+     * domain string for either; these two are kernel-internal (not in
+     * clientApiId) and keep both apart from event signatures.
+     */
+    readonly cardAction: "gnomon:card-action:v1";
+    readonly presencePrompt: "gnomon:presence-prompt:v1";
+    /** #budget-fuse (M1.6): the kernel key signs every permit:v1 (§4.8 `sig`); kernel-internal domain. */
+    readonly permit: "gnomon:permit:v1";
+    /**
+     * #identity (M1.3): a hardware presence attestation — the approvals key
+     * (Secure Enclave, behind the signed helper; never the root, round 2 M1) signs a kernel challenge
+     * `<purpose>\n<bindingDigest>\n<connId>\n<challenge>` after the helper's
+     * presence prompt; the presence module mints a PresenceToken only on a
+     * verified one. Kernel-internal (not in clientApiId).
+     */
+    readonly presence: "gnomon:presence:v1";
+};
+type SignatureDomain = keyof typeof SIGNATURE_DOMAINS;
+/** §3.1 key classes that sign (the link key never signs; X25519, Noise only). */
+type KeyClass = 'kernel' | 'root' | 'approvals' | 'device' | 'agent' | 'readToken';
+/** Which domains each key class may sign (§3.1 "Signs:" per class). */
+declare const DOMAINS_BY_KEY_CLASS: Readonly<Record<KeyClass, readonly SignatureDomain[]>>;
+type KeyCustody = 'software' | 'hardware';
+interface Signer {
+    /** `gkey:v1:<sha256(normalized spki PEM)>` (Ed25519) or `gkey-p256:v1:…`. */
+    readonly keyId: string;
+    readonly keyClass: KeyClass;
+    readonly custody: KeyCustody;
+    /** Sign `domain + "\n" + message`; throws if this key class may not sign the domain. */
+    sign(domain: SignatureDomain, message: string): Uint8Array;
+}
+/** The exact bytes a signature covers. */
+declare function signaturePreimage(domain: SignatureDomain, message: string): Buffer;
+/** The approve-domain message (§3.1): approver in the preimage (Q5). */
+declare function approveMessage(f: {
+    cardId: string;
+    decision: string;
+    cardContentHash: string;
+    approverPrincipalId: string;
+}): string;
+/**
+ * #approval-broker decisionSig v2 (P8-D98, TD-2026-10-19-648, slice A2). The v2 layout (contracts
+ * decisionMessageV2) adds the answer digest, so a typed `answer{text}` binds the text the human approved:
+ *   gnomon:decision:v2 \n cardId \n decision \n cardContentHash \n approverPrincipalId \n answerDigest
+ * It is used ONLY for the DECISION_SIG_V2_DECISIONS (`answer`); every other decision keeps the v1
+ * approveMessage. The domain stays `gnomon:approve:v1`: the version lives in the message's first line.
+ */
+declare function usesDecisionV2(decision: string): boolean;
+/** sha256:<hex> of the UTF-8 answer text (the same bytes approval.decide records as noteHash). */
+declare function answerDigest(text: string): string;
+/**
+ * The decisionSig message for a decision: v2 for `answer` (answerDigest REQUIRED; a missing one throws,
+ * never a silent v1), v1 approveMessage otherwise (an answerDigest on a v1 decision throws: no ambiguity).
+ */
+declare function decisionMessage(f: {
+    cardId: string;
+    decision: string;
+    cardContentHash: string;
+    approverPrincipalId: string;
+    answerDigest?: string;
+    /** TD-2026-10-20-294: a prefix-scoped `always` signs v2 with the scope digest as its last line */
+    scopeDigest?: string;
+}): string;
+/** keyId for an Ed25519 public key: `gkey:v1:` + sha256(normalized spki PEM). */
+declare function ed25519KeyId(publicKeyPem: string): string;
+/** keyId for a P-256 public key: `gkey-p256:v1:` + sha256(spki DER). */
+declare function p256KeyId(publicKey: KeyObject): string;
+declare class SignerDomainError extends Error {
+    constructor(keyClass: KeyClass, domain: SignatureDomain);
+}
+/**
+ * The software Ed25519 signer — the kernel key held in memory (PR-4). Also the
+ * shape device and agent keys take (they are Ed25519 files, §3.1). Refuses to
+ * be constructed as a root or approvals key: those are hardware-only.
+ */
+declare class SoftwareEd25519Signer implements Signer {
+    #private;
+    readonly keyId: string;
+    readonly keyClass: KeyClass;
+    readonly custody: "software";
+    readonly publicKeyPem: string;
+    constructor(privateKeyPem: string, keyClass?: KeyClass);
+    /** A fresh in-memory kernel key (tests; production loads from the keystore). */
+    static generate(keyClass?: KeyClass): SoftwareEd25519Signer;
+    sign(domain: SignatureDomain, message: string): Uint8Array;
+}
+/**
+ * Public keys by keyId, for verification. M1.3 (#identity) fills it from the
+ * root-signed registry; PR-4 callers add keys directly. Never throws on
+ * malformed input: a bad signature or unknown key is simply `false`/`unknown`.
+ */
+declare class KeyRing {
+    #private;
+    addEd25519(publicKeyPem: string): string;
+    addP256(publicKey: KeyObject | string): string;
+    has(keyId: string): boolean;
+    verify(keyId: string, domain: SignatureDomain, message: string, sig: Uint8Array): 'ok' | 'bad' | 'unknown-key';
+}
+
+export { DOMAINS_BY_KEY_CLASS as D, KeyRing as K, SIGNATURE_DOMAINS as c, SignerDomainError as e, SoftwareEd25519Signer as f, answerDigest as g, approveMessage as h, decisionMessage as i, ed25519KeyId as j, p256KeyId as p, signaturePreimage as s, usesDecisionV2 as u };
+export type { Signer as S, KeyClass as a, KeyCustody as b, SignatureDomain as d };