@cello-protocol/client 0.0.2

package/dist/connection-policy.js

@@ -0,0 +1,248 @@
+/**
+ * @cello-protocol/client — CELLO-CONNPOL-001
+ * Connection policy engine.
+ *
+ * Evaluates an incoming connection package against a SignalRequirementPolicy
+ * and a DirectoryContext to produce a ConnectionReport.
+ *
+ * ──── Phase P: Pseudocode ────
+ *
+ * evaluateConnectionPackage(validatedPackage, policy, context, current_timestamp_ms):
+ *
+ *   1. If policy.mode === 'closed'
+ *        return { verdict: 'auto_reject', reason: 'policy_closed' }
+ *
+ *   2. If context.is_provisional === true
+ *        return { verdict: 'auto_reject', reason: 'is_provisional' }
+ *
+ *   3. If validatedPackage.valid === false
+ *        return { verdict: 'auto_reject', reason: 'pseudonym_binding_invalid' }
+ *
+ *   4. If policy.mode === 'open' && policy.review_mode === 'deterministic'
+ *        return { verdict: 'auto_accept' }
+ *
+ *   5. If policy.mode === 'open' && policy.review_mode === 'inference'
+ *        return { verdict: 'pending_agent_review', ... zero unmet requirements ... }
+ *
+ *   6. For mode 'selective' | 'guarded' (identical in M3):
+ *        evaluate each requirement → collect met[] and unmet[]
+ *        if review_mode === 'deterministic':
+ *          unmet.length === 0 → auto_accept
+ *          unmet.length > 0  → auto_insufficient
+ *        if review_mode === 'inference':
+ *          → pending_agent_review (always, with met/unmet summary)
+ *
+ * Requirement evaluation (evaluateRequirement):
+ *
+ *   endorsement + min_count:
+ *     count = endorsements.filter(e => e.validation_status === 'valid').length
+ *     met iff count >= condition.count
+ *     unmet: { signal_type: 'endorsement', condition, provided: count }
+ *
+ *   pseudonym_age + min_age_days:
+ *     age = floor((current_timestamp_ms - pseudonym_binding.created_at) / 86_400_000)
+ *     met iff age >= condition.days
+ *     unmet: { signal_type: 'pseudonym_age', condition, provided_days: age }
+ *
+ *   registration_age + min_age_days:
+ *     age = floor((current_timestamp_ms - context.registered_at) / 86_400_000)
+ *     met iff age >= condition.days
+ *     unmet: { signal_type: 'registration_age', condition, provided_days: age }
+ *
+ *   attestation + attestation_type:
+ *     for each type in condition.required: check at least one valid attestation with that type
+ *     missing_types = types where no valid attestation exists
+ *     met iff missing_types.length === 0
+ *     unmet: { signal_type: 'attestation', condition, missing_types }
+ *
+ *   any requirement with from_shared_contact condition:
+ *     unsatisfiable in M3 → { signal_type, condition, unsupported_condition: true }
+ *
+ * References:
+ *   CELLO-CONNPOL-001 story YAML
+ */
+// ─── Default policies ─────────────────────────────────────────────────────────
+export const OPEN_POLICY = {
+    mode: "open",
+    review_mode: "inference",
+    requirements: [],
+};
+export const SELECTIVE_DEFAULT = {
+    mode: "selective",
+    review_mode: "inference",
+    requirements: [{ signal_type: "endorsement", condition: { type: "min_count", count: 1 } }],
+};
+export const CLOSED_POLICY = {
+    mode: "closed",
+    review_mode: "deterministic",
+    requirements: [],
+};
+// ─── Engine ───────────────────────────────────────────────────────────────────
+/**
+ * Evaluate an incoming connection package against a policy and directory context.
+ *
+ * Evaluation order is hard-coded and non-negotiable:
+ *   1. closed → auto_reject: policy_closed
+ *   2. is_provisional → auto_reject: is_provisional
+ *   3. package.valid === false → auto_reject: pseudonym_binding_invalid
+ *   4. open + deterministic → auto_accept
+ *   5. open + inference → pending_agent_review (zero requirements)
+ *   6. selective/guarded: evaluate requirements, then:
+ *      - deterministic + all met → auto_accept
+ *      - deterministic + any unmet → auto_insufficient
+ *      - inference → pending_agent_review (with met/unmet lists)
+ */
+export function evaluateConnectionPackage(validatedPackage, policy, context, current_timestamp_ms) {
+    // Step 1: closed mode — reject before any other check
+    if (policy.mode === "closed") {
+        return { verdict: "auto_reject", reason: "policy_closed" };
+    }
+    // Step 2: provisional agent — cannot receive connections
+    if (context.is_provisional) {
+        return { verdict: "auto_reject", reason: "is_provisional" };
+    }
+    // Step 3: invalid package — pseudonym binding failed
+    if (!validatedPackage.valid) {
+        return { verdict: "auto_reject", reason: "pseudonym_binding_invalid" };
+    }
+    // From here: validatedPackage is valid (valid: true branch)
+    const pkg = validatedPackage;
+    // Step 4: open + deterministic → auto_accept
+    if (policy.mode === "open" && policy.review_mode === "deterministic") {
+        return { verdict: "auto_accept" };
+    }
+    // Step 5: open + inference → pending_agent_review with zero requirements
+    if (policy.mode === "open" && policy.review_mode === "inference") {
+        return {
+            verdict: "pending_agent_review",
+            policy_summary: {
+                mode: policy.mode,
+                review_mode: "inference",
+                requirements_met: [],
+                requirements_unmet: [],
+            },
+            package_summary: buildPackageSummary(pkg, context, current_timestamp_ms),
+            is_round_2: false,
+        };
+    }
+    // Step 6: selective | guarded — evaluate requirements
+    const metRequirements = [];
+    const unmetRequirements = [];
+    for (const req of policy.requirements) {
+        const result = evaluateRequirement(req, pkg, context, current_timestamp_ms);
+        if (result === null) {
+            metRequirements.push(req);
+        }
+        else {
+            unmetRequirements.push(result);
+        }
+    }
+    if (policy.review_mode === "deterministic") {
+        if (unmetRequirements.length === 0) {
+            return { verdict: "auto_accept" };
+        }
+        return { verdict: "auto_insufficient", unmet_requirements: unmetRequirements };
+    }
+    // review_mode === 'inference'
+    return {
+        verdict: "pending_agent_review",
+        policy_summary: {
+            mode: policy.mode,
+            review_mode: "inference",
+            requirements_met: metRequirements,
+            requirements_unmet: unmetRequirements,
+        },
+        package_summary: buildPackageSummary(pkg, context, current_timestamp_ms),
+        is_round_2: false,
+    };
+}
+// ─── Requirement evaluation ───────────────────────────────────────────────────
+/**
+ * Evaluate a single requirement.
+ *
+ * Returns null if met, or an UnmetRequirement if not.
+ */
+function evaluateRequirement(req, pkg, context, current_timestamp_ms) {
+    const { condition } = req;
+    // from_shared_contact is M6-only — always unsatisfiable in M3
+    if (condition.type === "from_shared_contact") {
+        return { signal_type: req.signal_type, condition, unsupported_condition: true };
+    }
+    switch (req.signal_type) {
+        case "endorsement":
+            return evaluateEndorsementRequirement(condition, pkg.endorsements);
+        case "pseudonym_age":
+            return evaluatePseudonymAgeRequirement(condition, pkg.pseudonym_binding.created_at, current_timestamp_ms);
+        case "registration_age":
+            return evaluateRegistrationAgeRequirement(condition, context.registered_at, current_timestamp_ms);
+        case "attestation":
+            return evaluateAttestationRequirement(condition, pkg.attestations);
+        default:
+            // Unknown signal_type — treat as unsupported
+            return { signal_type: req.signal_type, condition, unsupported_condition: true };
+    }
+}
+function evaluateEndorsementRequirement(condition, endorsements) {
+    if (condition.type === "min_count") {
+        const validCount = endorsements.filter((e) => e.validation_status === "valid").length;
+        if (validCount >= condition.count) {
+            return null;
+        }
+        return { signal_type: "endorsement", condition, provided: validCount };
+    }
+    // Unrecognized condition for endorsement — unsupported
+    return { signal_type: "endorsement", condition, unsupported_condition: true };
+}
+function evaluatePseudonymAgeRequirement(condition, created_at, current_timestamp_ms) {
+    if (condition.type === "min_age_days") {
+        const ageDays = Math.floor((current_timestamp_ms - created_at) / 86_400_000);
+        if (ageDays >= condition.days) {
+            return null;
+        }
+        return { signal_type: "pseudonym_age", condition, provided_days: ageDays };
+    }
+    return { signal_type: "pseudonym_age", condition, unsupported_condition: true };
+}
+function evaluateRegistrationAgeRequirement(condition, registered_at, current_timestamp_ms) {
+    if (condition.type === "min_age_days") {
+        const ageDays = Math.floor((current_timestamp_ms - registered_at) / 86_400_000);
+        if (ageDays >= condition.days) {
+            return null;
+        }
+        return { signal_type: "registration_age", condition, provided_days: ageDays };
+    }
+    return { signal_type: "registration_age", condition, unsupported_condition: true };
+}
+function evaluateAttestationRequirement(condition, attestations) {
+    if (condition.type === "attestation_type") {
+        const validAttestationTypes = new Set(attestations
+            .filter((a) => a.validation_status === "valid")
+            .map((a) => a.attestation_type));
+        const missingTypes = condition.required.filter((t) => !validAttestationTypes.has(t));
+        if (missingTypes.length === 0) {
+            return null;
+        }
+        return { signal_type: "attestation", condition, missing_types: missingTypes };
+    }
+    return { signal_type: "attestation", condition, unsupported_condition: true };
+}
+// ─── Package summary builder ──────────────────────────────────────────────────
+function buildPackageSummary(pkg, context, current_timestamp_ms) {
+    const pseudonymAgeDays = Math.floor((current_timestamp_ms - pkg.pseudonym_binding.created_at) / 86_400_000);
+    const registrationAgeDays = Math.floor((current_timestamp_ms - context.registered_at) / 86_400_000);
+    const validEndorsementCount = pkg.endorsements.filter((e) => e.validation_status === "valid").length;
+    const validAttestationTypes = [
+        ...new Set(pkg.attestations
+            .filter((a) => a.validation_status === "valid")
+            .map((a) => a.attestation_type)),
+    ];
+    return {
+        pseudonym_label: pkg.pseudonym_binding.pseudonym_label,
+        endorsement_count: validEndorsementCount,
+        attestation_types: validAttestationTypes,
+        pseudonym_age_days: pseudonymAgeDays,
+        registration_age_days: registrationAgeDays,
+        is_provisional: context.is_provisional,
+    };
+}
+//# sourceMappingURL=connection-policy.js.map

package/dist/connection-policy.js.map

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

package/dist/db-key-derivation.d.ts

@@ -0,0 +1,26 @@
+/**
+ * db-key-derivation.ts — HKDF derivation of the local database encryption key.
+ *
+ * PERSIST-009: db_key = HKDF-SHA256(ikm=identity_key, salt=none, info='local-db-key' || agent_id, length=32)
+ *
+ * Security invariants (PERSIST-009 SI-002):
+ *   - identity_key is passed in by the caller; it is NEVER stored here.
+ *   - The returned db_key is NEVER logged or persisted by this function.
+ *   - This function has no side effects — pure transformation only.
+ *
+ * RFC reference: RFC 5869 (HKDF). Node.js implementation: crypto.hkdfSync.
+ */
+/**
+ * Derive a 32-byte database encryption key from the agent's identity_key.
+ *
+ * @param identityKey - The agent's long-term root key (32 bytes). Never stored or logged.
+ * @param agentId     - The stable agent identifier. Binds the key to a specific agent.
+ * @returns           - A 32-byte Uint8Array suitable for use as a SQLCipher PRAGMA key.
+ *
+ * Security: The db_key is deterministic — same inputs always produce the same output.
+ * This is intentional: the client must re-derive the key on every startup without
+ * storing it, using only the identity_key (which is stored separately, protected
+ * by the OS keychain or equivalent).
+ */
+export declare function deriveDbKey(identityKey: Uint8Array, agentId: string): Uint8Array;
+//# sourceMappingURL=db-key-derivation.d.ts.map

package/dist/db-key-derivation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"db-key-derivation.d.ts","sourceRoot":"","sources":["../src/db-key-derivation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAIH;;;;;;;;;;;GAWG;AACH,wBAAgB,WAAW,CAAC,WAAW,EAAE,UAAU,EAAE,OAAO,EAAE,MAAM,GAAG,UAAU,CAYhF"}

package/dist/db-key-derivation.js

@@ -0,0 +1,37 @@
+/**
+ * db-key-derivation.ts — HKDF derivation of the local database encryption key.
+ *
+ * PERSIST-009: db_key = HKDF-SHA256(ikm=identity_key, salt=none, info='local-db-key' || agent_id, length=32)
+ *
+ * Security invariants (PERSIST-009 SI-002):
+ *   - identity_key is passed in by the caller; it is NEVER stored here.
+ *   - The returned db_key is NEVER logged or persisted by this function.
+ *   - This function has no side effects — pure transformation only.
+ *
+ * RFC reference: RFC 5869 (HKDF). Node.js implementation: crypto.hkdfSync.
+ */
+import { hkdfSync } from "node:crypto";
+/**
+ * Derive a 32-byte database encryption key from the agent's identity_key.
+ *
+ * @param identityKey - The agent's long-term root key (32 bytes). Never stored or logged.
+ * @param agentId     - The stable agent identifier. Binds the key to a specific agent.
+ * @returns           - A 32-byte Uint8Array suitable for use as a SQLCipher PRAGMA key.
+ *
+ * Security: The db_key is deterministic — same inputs always produce the same output.
+ * This is intentional: the client must re-derive the key on every startup without
+ * storing it, using only the identity_key (which is stored separately, protected
+ * by the OS keychain or equivalent).
+ */
+export function deriveDbKey(identityKey, agentId) {
+    // info = 'local-db-key' || NUL || agentId (UTF-8 encoded).
+    // The null-byte separator prevents a theoretical prefix-collision where two
+    // different (literal, agentId) pairs could produce the same concatenation.
+    const infoStr = `local-db-key\x00${agentId}`;
+    const info = Buffer.from(infoStr, "utf8");
+    // HKDF-SHA256: salt=none (empty Buffer), length=32 bytes
+    // RFC 5869 §2.2: when salt is not provided, a string of HashLen zeros is used.
+    const derived = hkdfSync("sha256", identityKey, Buffer.alloc(0), info, 32);
+    return new Uint8Array(derived);
+}
+//# sourceMappingURL=db-key-derivation.js.map

package/dist/db-key-derivation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"db-key-derivation.js","sourceRoot":"","sources":["../src/db-key-derivation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAEvC;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,WAAW,CAAC,WAAuB,EAAE,OAAe;IAClE,2DAA2D;IAC3D,4EAA4E;IAC5E,2EAA2E;IAC3E,MAAM,OAAO,GAAG,mBAAmB,OAAO,EAAE,CAAC;IAC7C,MAAM,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;IAE1C,yDAAyD;IACzD,+EAA+E;IAC/E,MAAM,OAAO,GAAG,QAAQ,CAAC,QAAQ,EAAE,WAAW,EAAE,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,EAAE,CAAC,CAAC;IAE3E,OAAO,IAAI,UAAU,CAAC,OAAO,CAAC,CAAC;AACjC,CAAC"}

package/dist/encrypted-file-signing-key-provider.d.ts

@@ -0,0 +1,92 @@
+/**
+ * EncryptedFileSigningKeyProvider — file-backed SigningKeyProvider for CELLO_ENV=local/dev.
+ *
+ * PERSIST-010: Reads the Ed25519 private key seed from an encrypted key file at the
+ * configured path, decrypts it into memory for signing, and zeroes the in-memory key
+ * buffer after each sign() call (SI-002).
+ *
+ * The private key NEVER crosses the provider boundary (SI-001). The only exported
+ * values are the public key (via getPublicKey()) and signatures (via sign()).
+ *
+ * Key file format (same as FileKeyProvider in @cello-protocol/crypto):
+ *   Bytes 0–3:   Magic [0xCE, 0x11, 0x0E, 0x01]
+ *   Byte 4:      Version (0x01)
+ *   Bytes 5–36:  32-byte Ed25519 seed
+ *
+ * This file is NOT exported from packages/client/src/index.ts.
+ * It is only imported by the composition root (server.ts).
+ *
+ * RFC reference: Ed25519 signing per RFC 8032.
+ */
+import type { SigningKeyProvider, SigningPublicKey, SigningSignature, SignOptions } from "@cello-protocol/interfaces";
+import type { Logger } from "@cello-protocol/interfaces";
+export interface EncryptedFileSigningKeyProviderOptions {
+    /** Stable agent identifier — used in log events. */
+    agentId: string;
+    /** Structured logger injected from the composition root. */
+    logger: Logger;
+}
+/**
+ * SigningKeyProvider backed by an encrypted key file on disk.
+ *
+ * Lifecycle: EncryptedFileSigningKeyProvider.load(path, opts) → ready to sign.
+ *
+ * On each sign() call, the seed is read from the file into a temporary buffer,
+ * used for signing, and the buffer is zeroed immediately after — even on throw.
+ * This ensures the private key exists in process memory only for the minimum
+ * time required to produce the signature.
+ *
+ * Security invariants:
+ *   SI-001: No method returns/exports the private key.
+ *   SI-002: Key buffer zeroed after EVERY sign() call, even on throw (try/finally).
+ *   SI-003: sign() failure propagates — never falls back to weaker signing.
+ */
+export declare class EncryptedFileSigningKeyProvider implements SigningKeyProvider {
+    #private;
+    private constructor();
+    /**
+     * Load the signing key from the key file at the given path.
+     *
+     * Validates the file format and derives the public key. The seed itself
+     * is not retained — it is re-read from the file on each sign() call.
+     *
+     * Throws SigningKeyProviderError if:
+     *   - File not found (reason: 'key_file_not_found')
+     *   - File corrupt (reason: 'key_file_corrupt')
+     *
+     * @param path - Absolute path to the encrypted key file (SIGNING_KEY_PATH)
+     * @param opts - Configuration including agentId and logger
+     */
+    static load(path: string, opts: EncryptedFileSigningKeyProviderOptions): Promise<EncryptedFileSigningKeyProvider>;
+    /** Return the 32-byte Ed25519 public key. */
+    getPublicKey(): Promise<SigningPublicKey>;
+    /**
+     * Sign data with the Ed25519 private key.
+     *
+     * Security: On each call, the seed is re-read from the key file into a
+     * working buffer, used for signing, and the buffer is zeroed in a finally
+     * block — even if signing throws (SI-002).
+     *
+     * The public key is derived once at load() and cached — it is not sensitive.
+     */
+    sign(data: Uint8Array, opts?: SignOptions): Promise<SigningSignature>;
+    /**
+     * @internal Test seam — returns true if the working buffer is currently all-zeros.
+     * This does NOT expose key material. Tests use this to verify SI-002 (zeroing)
+     * without ever seeing the private key bytes.
+     */
+    isKeyBufferZeroedForTesting(): boolean;
+    /**
+     * @internal Test seam — corrupts the provider state to trigger sign() failures
+     * BEFORE the key file is read. Used to test SI-003 (no fallback).
+     * Note: does NOT exercise the try/finally zeroing path — use throwAfterLoadForTesting() for that.
+     */
+    corruptForTesting(): void;
+    /**
+     * @internal Test seam — causes sign() to throw AFTER the key has been loaded into
+     * the working buffer but BEFORE ed25519.sign() is called. Used to verify SI-002:
+     * the finally block zeroes the key buffer even when sign() throws mid-operation.
+     */
+    throwAfterLoadForTesting(): void;
+}
+//# sourceMappingURL=encrypted-file-signing-key-provider.d.ts.map

package/dist/encrypted-file-signing-key-provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"encrypted-file-signing-key-provider.d.ts","sourceRoot":"","sources":["../src/encrypted-file-signing-key-provider.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAIH,OAAO,KAAK,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,WAAW,EAAE,MAAM,4BAA4B,CAAC;AAEtH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,4BAA4B,CAAC;AAWzD,MAAM,WAAW,sCAAsC;IACrD,oDAAoD;IACpD,OAAO,EAAE,MAAM,CAAC;IAChB,4DAA4D;IAC5D,MAAM,EAAE,MAAM,CAAC;CAChB;AAKD;;;;;;;;;;;;;;GAcG;AACH,qBAAa,+BAAgC,YAAW,kBAAkB;;IAiBxE,OAAO;IAYP;;;;;;;;;;;;OAYG;WACU,IAAI,CACf,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,sCAAsC,GAC3C,OAAO,CAAC,+BAA+B,CAAC;IAwC3C,6CAA6C;IACvC,YAAY,IAAI,OAAO,CAAC,gBAAgB,CAAC;IAI/C;;;;;;;;OAQG;IACG,IAAI,CAAC,IAAI,EAAE,UAAU,EAAE,IAAI,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,gBAAgB,CAAC;IAkE3E;;;;OAIG;IACH,2BAA2B,IAAI,OAAO;IAItC;;;;OAIG;IACH,iBAAiB,IAAI,IAAI;IAIzB;;;;OAIG;IACH,wBAAwB,IAAI,IAAI;CAGjC"}