@cello-protocol/daemon 0.0.227 → 0.0.228

package/dist/contacts-tier-migration.d.ts

@@ -0,0 +1,90 @@
+/**
+ * CELLO Daemon — contacts tier metadata (DOD-TIER-1, address-book Step 1).
+ *
+ * `contacts` was re-keyed to the stable `agent_id` in daemon@0.0.45 (DOD-AGENT-ID-JOINKEY-1). This
+ * module lands the address-book's per-contact metadata ON that key: a reachability `tier`, the
+ * `provenance` of the relationship, the last self-declared name a peer offered (for Option-C rename
+ * detection, Step 3), and a per-contact `away_message` (Step 4). All four are pure ADD COLUMN — no
+ * table rebuild, no PK change — so, unlike the join-key migration, this one is simple and idempotent
+ * and never has to appear in that migration's pinned DDL. It runs AFTER `migrateSessionTablesToAgentId`.
+ *
+ * Design source: docs/planning/user-stories/m8c/2026-07-10_contact-address-book-design.md (§1).
+ */
+import type { DaemonDatabase } from "./sqlcipher-db.js";
+import type { Logger } from "./types.js";
+/**
+ * The five reachability tiers, ordered so `>=` is meaningful (blocked < unknown < known < whitelisted
+ * < vip). Stored as the INTEGER `contacts.tier`. This const map is the SINGLE source of the numbers;
+ * no bare tier integer may appear at a call site (DOD-TIER-1 AC2).
+ *
+ * BLOCKED is a real, meaningful ZERO — see `normalizeTier` for why that matters.
+ */
+export declare const TIER: Readonly<{
+    readonly BLOCKED: 0;
+    readonly UNKNOWN: 1;
+    readonly KNOWN: 2;
+    readonly WHITELISTED: 3;
+    readonly VIP: 4;
+}>;
+export type TierName = keyof typeof TIER;
+export type TierValue = (typeof TIER)[TierName];
+/** True iff `n` is exactly one of the five defined tier integers (0..4). The validation gate for
+ *  `cello_contact_set_tier` (Step 3) — an unknown value is refused, never coerced. */
+export declare function isKnownTierValue(n: number): boolean;
+/**
+ * The read-side default, and the single most safety-critical function in this unit.
+ *
+ * A contact's effective tier is UNKNOWN when there is NO row (undefined) OR when the row's `tier`
+ * column is NULL (a row that predates a tier being set, or a stray never-stamped row). Both collapse
+ * to UNKNOWN — the tighter default: a caller must never accidentally treat an unresolved contact as
+ * reachable.
+ *
+ * It is written with EXPLICIT null/undefined checks, never `tier || UNKNOWN`, for two reasons that
+ * are both live bugs otherwise:
+ *   - `0 || 1 === 1`: a `|| UNKNOWN` would swallow BLOCKED(0) and silently un-block a blocked contact.
+ *   - `null >= 0 === true`: a NULL reaching a `>=` bound check reads as "not blocked", and a NULL
+ *     reaching a `grid[tier]` lookup is `grid[null]` → undefined → crash. Normalizing NULL→UNKNOWN
+ *     here keeps every downstream comparison and lookup total.
+ */
+export declare function normalizeTier(tier: number | null | undefined): number;
+/** DOD-TIER-2: the abuse bounds for one tier. INV-TIER-BOUND — every field is FINITE (no tier is
+ *  unbounded; `vip` is a large but real number, never Infinity). Step 4 lets settings OVERRIDE these
+ *  defaults, but a setting may only raise/lower within finite bounds, never remove one. */
+export interface TierBound {
+    /** Max concurrent (active|interrupted) sessions this agent will hold from ONE sender at this tier. */
+    readonly maxSessionsPerSender: number;
+    /** Max cumulative RECEIVED bytes for a single session at this tier (anti-drip-feed). */
+    readonly maxBytesPerSession: number;
+}
+/**
+ * The hardcoded default bounds grid (DOD-TIER-2). One named map — the SINGLE source; call sites
+ * reference it via `tierBoundsFor`, never inline a number. Step 4 (DOD-TIER-BOUNDS-SETTINGS) makes
+ * these overridable per agent; until then they are the policy.
+ *
+ * INV-TIER-BOUND: a HIGHER tier only RAISES a bound — no tier removes one. `vip` is 50 sessions / 2 GiB,
+ * deliberately finite. `blocked` is 0/0, which is what makes DOD-TIER-3 fall out for free: a 0 session
+ * cap refuses a blocked sender through the SAME per-sender-cap path an over-cap unknown takes, with no
+ * separate branch and therefore no distinguishing oracle.
+ */
+export declare const DEFAULT_TIER_BOUNDS: Readonly<Record<number, TierBound>>;
+/** The bounds for a tier, TOTAL: any input is normalized to a defined tier first, so the return is
+ *  always a real `TierBound` — a corrupt/out-of-range tier gets UNKNOWN's bounds, never `undefined`
+ *  (the `grid[99]` crash the whole tier design guards against). */
+export declare function tierBoundsFor(tier: number | null | undefined): TierBound;
+/**
+ * Idempotently add the tier-metadata columns to `contacts` and grandfather existing contacts.
+ *
+ * SQLite has no `ADD COLUMN IF NOT EXISTS`, so each ALTER is PRAGMA-guarded. Crucially the columns
+ * are added with NO DEFAULT: a `DEFAULT` would give every existing row a value the instant the column
+ * is created, so the grandfather backfill (`UPDATE … WHERE tier IS NULL`) would then match NOTHING —
+ * every auto-accepting contact would silently drop to UNKNOWN. No default → existing rows read NULL →
+ * the explicit backfill promotes them to WHITELISTED, preserving today's binary-whitelist behaviour
+ * (design §1). Silently revoking access people already rely on is a worse failure than grandfathering
+ * a permissive default for a handful of contacts they can list and demote at leisure.
+ *
+ * The grandfather is ONE-TIME: it runs only in the invocation that first adds the `tier` column. A
+ * NULL that appears later (a stray un-stamped row) is NOT promoted — it is read as UNKNOWN by
+ * `normalizeTier`, the tighter default. The promotion is tied to the column's birth, not to NULL-ness.
+ */
+export declare function migrateContactsAddTierMetadata(db: DaemonDatabase, logger: Logger): void;
+//# sourceMappingURL=contacts-tier-migration.d.ts.map

package/dist/contacts-tier-migration.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"contacts-tier-migration.d.ts","sourceRoot":"","sources":["../src/contacts-tier-migration.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AACxD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,YAAY,CAAC;AAGzC;;;;;;GAMG;AACH,eAAO,MAAM,IAAI;;;;;;EAMN,CAAC;AAEZ,MAAM,MAAM,QAAQ,GAAG,MAAM,OAAO,IAAI,CAAC;AACzC,MAAM,MAAM,SAAS,GAAG,CAAC,OAAO,IAAI,CAAC,CAAC,QAAQ,CAAC,CAAC;AAIhD;sFACsF;AACtF,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO,CAEnD;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM,CAQrE;AAED;;2FAE2F;AAC3F,MAAM,WAAW,SAAS;IACxB,sGAAsG;IACtG,QAAQ,CAAC,oBAAoB,EAAE,MAAM,CAAC;IACtC,wFAAwF;IACxF,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAC;CACrC;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,mBAAmB,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,CAMlE,CAAC;AAEH;;mEAEmE;AACnE,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,SAAS,CAExE;AAeD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,8BAA8B,CAAC,EAAE,EAAE,cAAc,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CA8CvF"}

package/dist/contacts-tier-migration.js

@@ -0,0 +1,150 @@
+/**
+ * CELLO Daemon — contacts tier metadata (DOD-TIER-1, address-book Step 1).
+ *
+ * `contacts` was re-keyed to the stable `agent_id` in daemon@0.0.45 (DOD-AGENT-ID-JOINKEY-1). This
+ * module lands the address-book's per-contact metadata ON that key: a reachability `tier`, the
+ * `provenance` of the relationship, the last self-declared name a peer offered (for Option-C rename
+ * detection, Step 3), and a per-contact `away_message` (Step 4). All four are pure ADD COLUMN — no
+ * table rebuild, no PK change — so, unlike the join-key migration, this one is simple and idempotent
+ * and never has to appear in that migration's pinned DDL. It runs AFTER `migrateSessionTablesToAgentId`.
+ *
+ * Design source: docs/planning/user-stories/m8c/2026-07-10_contact-address-book-design.md (§1).
+ */
+import { extractErrorMessage } from "./error-message.js";
+/**
+ * The five reachability tiers, ordered so `>=` is meaningful (blocked < unknown < known < whitelisted
+ * < vip). Stored as the INTEGER `contacts.tier`. This const map is the SINGLE source of the numbers;
+ * no bare tier integer may appear at a call site (DOD-TIER-1 AC2).
+ *
+ * BLOCKED is a real, meaningful ZERO — see `normalizeTier` for why that matters.
+ */
+export const TIER = Object.freeze({
+    BLOCKED: 0,
+    UNKNOWN: 1,
+    KNOWN: 2,
+    WHITELISTED: 3,
+    VIP: 4,
+});
+const TIER_VALUES = Object.freeze(Object.values(TIER));
+/** True iff `n` is exactly one of the five defined tier integers (0..4). The validation gate for
+ *  `cello_contact_set_tier` (Step 3) — an unknown value is refused, never coerced. */
+export function isKnownTierValue(n) {
+    return Number.isInteger(n) && TIER_VALUES.includes(n);
+}
+/**
+ * The read-side default, and the single most safety-critical function in this unit.
+ *
+ * A contact's effective tier is UNKNOWN when there is NO row (undefined) OR when the row's `tier`
+ * column is NULL (a row that predates a tier being set, or a stray never-stamped row). Both collapse
+ * to UNKNOWN — the tighter default: a caller must never accidentally treat an unresolved contact as
+ * reachable.
+ *
+ * It is written with EXPLICIT null/undefined checks, never `tier || UNKNOWN`, for two reasons that
+ * are both live bugs otherwise:
+ *   - `0 || 1 === 1`: a `|| UNKNOWN` would swallow BLOCKED(0) and silently un-block a blocked contact.
+ *   - `null >= 0 === true`: a NULL reaching a `>=` bound check reads as "not blocked", and a NULL
+ *     reaching a `grid[tier]` lookup is `grid[null]` → undefined → crash. Normalizing NULL→UNKNOWN
+ *     here keeps every downstream comparison and lookup total.
+ */
+export function normalizeTier(tier) {
+    if (tier === null || tier === undefined)
+        return TIER.UNKNOWN;
+    // TOTAL over ALL inputs: a stored value that is not one of the five defined tiers (a corrupt or
+    // future-version row) also collapses to UNKNOWN, so `getTier` is guaranteed to return a value in
+    // 0..4 and every downstream `grid[tier]` lookup / `>=` comparison is total. Without this, a corrupt
+    // `tier = 99` would sail through and become the `grid[99] → undefined` crash the bound grid fears.
+    if (!isKnownTierValue(tier))
+        return TIER.UNKNOWN;
+    return tier;
+}
+/**
+ * The hardcoded default bounds grid (DOD-TIER-2). One named map — the SINGLE source; call sites
+ * reference it via `tierBoundsFor`, never inline a number. Step 4 (DOD-TIER-BOUNDS-SETTINGS) makes
+ * these overridable per agent; until then they are the policy.
+ *
+ * INV-TIER-BOUND: a HIGHER tier only RAISES a bound — no tier removes one. `vip` is 50 sessions / 2 GiB,
+ * deliberately finite. `blocked` is 0/0, which is what makes DOD-TIER-3 fall out for free: a 0 session
+ * cap refuses a blocked sender through the SAME per-sender-cap path an over-cap unknown takes, with no
+ * separate branch and therefore no distinguishing oracle.
+ */
+export const DEFAULT_TIER_BOUNDS = Object.freeze({
+    [TIER.BLOCKED]: { maxSessionsPerSender: 0, maxBytesPerSession: 0 },
+    [TIER.UNKNOWN]: { maxSessionsPerSender: 3, maxBytesPerSession: 25 * 1024 * 1024 },
+    [TIER.KNOWN]: { maxSessionsPerSender: 5, maxBytesPerSession: 100 * 1024 * 1024 },
+    [TIER.WHITELISTED]: { maxSessionsPerSender: 20, maxBytesPerSession: 500 * 1024 * 1024 },
+    [TIER.VIP]: { maxSessionsPerSender: 50, maxBytesPerSession: 2 * 1024 * 1024 * 1024 },
+});
+/** The bounds for a tier, TOTAL: any input is normalized to a defined tier first, so the return is
+ *  always a real `TierBound` — a corrupt/out-of-range tier gets UNKNOWN's bounds, never `undefined`
+ *  (the `grid[99]` crash the whole tier design guards against). */
+export function tierBoundsFor(tier) {
+    return DEFAULT_TIER_BOUNDS[normalizeTier(tier)];
+}
+const TIER_METADATA_COLUMNS = [
+    { name: "tier", ddl: "tier INTEGER" },
+    { name: "provenance", ddl: "provenance TEXT" },
+    { name: "last_offered_moniker", ddl: "last_offered_moniker TEXT" },
+    { name: "away_message", ddl: "away_message TEXT" },
+];
+/**
+ * Idempotently add the tier-metadata columns to `contacts` and grandfather existing contacts.
+ *
+ * SQLite has no `ADD COLUMN IF NOT EXISTS`, so each ALTER is PRAGMA-guarded. Crucially the columns
+ * are added with NO DEFAULT: a `DEFAULT` would give every existing row a value the instant the column
+ * is created, so the grandfather backfill (`UPDATE … WHERE tier IS NULL`) would then match NOTHING —
+ * every auto-accepting contact would silently drop to UNKNOWN. No default → existing rows read NULL →
+ * the explicit backfill promotes them to WHITELISTED, preserving today's binary-whitelist behaviour
+ * (design §1). Silently revoking access people already rely on is a worse failure than grandfathering
+ * a permissive default for a handful of contacts they can list and demote at leisure.
+ *
+ * The grandfather is ONE-TIME: it runs only in the invocation that first adds the `tier` column. A
+ * NULL that appears later (a stray un-stamped row) is NOT promoted — it is read as UNKNOWN by
+ * `normalizeTier`, the tighter default. The promotion is tied to the column's birth, not to NULL-ness.
+ */
+export function migrateContactsAddTierMetadata(db, logger) {
+    const existing = new Set(db.prepare("PRAGMA table_info(contacts)").all().map((c) => c.name));
+    const toAdd = TIER_METADATA_COLUMNS.filter((c) => !existing.has(c.name));
+    if (toAdd.length === 0)
+        return; // idempotent: every column already present → nothing to do
+    // The ADD COLUMNs and the grandfather backfill MUST commit atomically, in ONE transaction (SQLite
+    // DDL is transactional — the same reason the join-key migration uses one BEGIN…COMMIT). If a crash
+    // landed between the `tier` ALTER committing and the backfill, the next init would see the column
+    // exists, skip the one-time grandfather FOREVER, and silently demote every legacy contact to
+    // UNKNOWN — the exact "silently revoking access people already rely on" failure this file exists to
+    // avoid, with no log and no error. Wrapping both makes "column added" and "existing rows
+    // grandfathered" inseparable: a crash rolls back BOTH, and the clean re-run does the whole thing —
+    // which is what makes column-existence a VALID durability marker for the one-time gate.
+    const addsTier = toAdd.some((c) => c.name === "tier");
+    let grandfathered = 0;
+    db.exec("BEGIN");
+    try {
+        for (const col of toAdd)
+            db.exec(`ALTER TABLE contacts ADD COLUMN ${col.ddl}`);
+        // Grandfather EXISTING contacts to WHITELISTED — but ONLY on the migration that first adds `tier`
+        // (a one-time, column-birth event). A NULL written AFTER the column exists is never promoted here;
+        // it is a read-time UNKNOWN via normalizeTier, the tighter default.
+        if (addsTier) {
+            grandfathered = Number(db.prepare("UPDATE contacts SET tier = ? WHERE tier IS NULL").run(TIER.WHITELISTED).changes);
+        }
+        db.exec("COMMIT");
+    }
+    catch (err) {
+        // SQLite may have already aborted the transaction; a failing ROLLBACK must not mask the real error.
+        try {
+            db.exec("ROLLBACK");
+        }
+        catch {
+            /* the failing statement may have already aborted the txn */
+        }
+        logger.error("contacts.tier.migration.failed", {
+            columns: toAdd.map((c) => c.name),
+            reason: extractErrorMessage(err),
+        });
+        throw err;
+    }
+    logger.info("contacts.tier.columns.added", { columns: toAdd.map((c) => c.name) });
+    if (grandfathered > 0) {
+        logger.info("contacts.tier.grandfathered", { count: grandfathered, tier: TIER.WHITELISTED });
+    }
+}
+//# sourceMappingURL=contacts-tier-migration.js.map

package/dist/contacts-tier-migration.js.map

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

package/dist/content-encryption-status.d.ts

@@ -0,0 +1,111 @@
+/**
+ * WHY A SESSION HAS NO AGREED CONTENT KEY — `DOD-M15-EPHEMERAL-AUTH-1` (007-CRYPTO).
+ *
+ * ─── The rule, and it is deliberately absolute ─────────────────────────────────────────────────
+ *
+ * **A live message body is encrypted under the agreed session key, or it is not sent.** There is no
+ * degraded mode, no "unencrypted but visibly so", and no negotiation.
+ *
+ * That is not strictness for its own sake — it is what removes an entire class of defect. A
+ * fallback to plaintext is a thing an attacker steers a session into: strip the key frame, and a
+ * system that "carries on, visibly degraded" hands over exactly the plaintext the attacker wanted,
+ * while the operator sees a warning they have learned to scroll past. The salt can degrade because
+ * a missing salt costs a correlation property; a missing KEY costs the message.
+ *
+ * ⚠️ AND THERE IS NO COMPATIBILITY CASE TO SERVE. CELLO is pre-launch with no external installs, so
+ * "the counterparty is on a build that predates this" is not a state anything is in. Every reason
+ * below is a FAULT — local, transient, or a counterparty that did not complete an exchange it is
+ * running the code for. None of them is an accepted steady state, and none of them may be described
+ * to an operator as one.
+ *
+ * ─── Not the same question as the salt ─────────────────────────────────────────────────────────
+ *
+ * `content_hashes_salted` is about a relay CONFIRMING a guess at a stored hash. This is about a
+ * relay READING the message. A session can be salted and unencrypted; it cannot send while
+ * unencrypted.
+ *
+ * ─── Why a closed set and a total map ──────────────────────────────────────────────────────────
+ *
+ * Copied from `refusal-reasons.ts`, which exists because a free-form `reason: string` let a new code
+ * slip past every test in its own guard file. A `Record` over the union means a reason cannot be
+ * added without something for the reader to do about it.
+ */
+/**
+ * The `content_encryption` marker on a `content_frame`, naming the scheme its body is under.
+ *
+ * On the WIRE rather than inferred, so a receiver never has to guess a layout from a length — and
+ * ABSENT is refused rather than read as plaintext. There is no unencrypted sender to accommodate, so
+ * a missing marker is not "an old peer", it is a frame something rewrote.
+ */
+export declare const SESSION_CONTENT_ENCRYPTION_V1 = "session-aes-256-gcm-v1";
+export declare const CONTENT_ENCRYPTION_REASONS: {
+    /**
+     * The exchange has not finished yet. Transient, and the ordinary state for the instant between a
+     * session opening and its first connect completing.
+     */
+    readonly NOT_YET_AGREED: "not_yet_agreed";
+    /**
+     * THIS machine has no identity key to sign its half with, so it cannot take part at all.
+     *
+     * Local setup fault — a signing-only or threshold provider, or an agent loaded without one. Named
+     * apart from the peer cases because "we could not sign" and "they did not answer" send the
+     * operator to opposite machines.
+     */
+    readonly NO_LOCAL_IDENTITY: "no_local_identity";
+    /** THIS side's half never left the machine. Local and transient; the next connect re-announces. */
+    readonly OUR_ANNOUNCE_FAILED: "our_announce_failed";
+    /**
+     * TERMINAL. The peer's key could not be tied to them and the session was stopped.
+     *
+     * ⚠️ THIS MUST SURVIVE THE TEARDOWN THAT FOLLOWS IT — review F2. The freeze destroys the session's
+     * key material, and clearing the reason with it left the listing recomputing `NOT_YET_AGREED`, so
+     * the one detection in this unit that means *someone may be substituting keys on your connection*
+     * reached the agent as "still agreeing, please wait". A security refusal that reads as a
+     * reassurance is worse than silence.
+     */
+    readonly KEY_REFUSED: "key_refused";
+    /**
+     * The counterparty never sent their half.
+     *
+     * NOT "they are on an old build" — they are running this code. Something between the two of you
+     * dropped the frame, or their daemon is not answering.
+     */
+    readonly PEER_SILENT: "peer_silent";
+};
+export type ContentEncryptionReason = (typeof CONTENT_ENCRYPTION_REASONS)[keyof typeof CONTENT_ENCRYPTION_REASONS];
+/**
+ * What the operator should DO. TOTAL over the union by construction.
+ *
+ * ⚠️ EVERY ENTRY NAMES A VERB THE READER CAN PERFORM, and none of them says "this is expected" —
+ * because none of these is. An affordance that resolves to nothing is worse than none, and a
+ * reassurance attached to a fault is worse than both.
+ */
+export declare const CONTENT_ENCRYPTION_GUIDANCE: Record<ContentEncryptionReason, string>;
+/**
+ * ⚠️ **THE SAME REASONS, TOLD TO THE OTHER DIRECTION** — `029c` review F6.
+ *
+ * `CONTENT_ENCRYPTION_GUIDANCE` above is written for the SEND path: it explains what became of a
+ * message THIS operator tried to send. The inbound refusal (`no_session_key`) was reusing it
+ * verbatim, so an operator who could not open an INCOMING message read advice about their own
+ * outbound mail — *"A message sent before it completes … goes to your counterparty's relay
+ * mailbox"* — two directions and two mailboxes in one paragraph.
+ *
+ * The CAUSE is identical, so the reason set is shared; only the consequence differs, so only the
+ * prose is. Total over the union for the same reason the other map is: a new reason cannot be added
+ * without deciding what it means to the receiving side.
+ */
+export declare const CONTENT_ENCRYPTION_INBOUND_GUIDANCE: Record<ContentEncryptionReason, string>;
+/**
+ * Render a reason for an agent.
+ *
+ * ⚠️ NO UNKNOWN-REASON FALLBACK, deliberately. The value is produced and consumed in one process
+ * from the closed set above — there is no column it is read back from and no other build writing
+ * one, so a "reason this version does not recognise" is a state nothing can be in. An earlier cut
+ * carried that branch anyway and described the value as coming off a database row, which was simply
+ * untrue. Unreachable defensive code that states a false provenance is worse than no code: it reads
+ * as a considered case and it is scaffolding for a world that does not exist.
+ *
+ * The map is TOTAL over the union, so the type is the check.
+ */
+export declare function contentEncryptionGuidanceFor(reason: ContentEncryptionReason): string;
+//# sourceMappingURL=content-encryption-status.d.ts.map

package/dist/content-encryption-status.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"content-encryption-status.d.ts","sourceRoot":"","sources":["../src/content-encryption-status.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAEH;;;;;;GAMG;AACH,eAAO,MAAM,6BAA6B,2BAA2B,CAAC;AAEtE,eAAO,MAAM,0BAA0B;IACrC;;;OAGG;;IAEH;;;;;;OAMG;;IAEH,mGAAmG;;IAEnG;;;;;;;;OAQG;;IAEH;;;;;OAKG;;CAEK,CAAC;AAEX,MAAM,MAAM,uBAAuB,GACjC,CAAC,OAAO,0BAA0B,CAAC,CAAC,MAAM,OAAO,0BAA0B,CAAC,CAAC;AAE/E;;;;;;GAMG;AACH,eAAO,MAAM,2BAA2B,EAAE,MAAM,CAAC,uBAAuB,EAAE,MAAM,CA6B/E,CAAC;AAEF;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,mCAAmC,EAAE,MAAM,CAAC,uBAAuB,EAAE,MAAM,CA2BvF,CAAC;AAEF;;;;;;;;;;;GAWG;AACH,wBAAgB,4BAA4B,CAAC,MAAM,EAAE,uBAAuB,GAAG,MAAM,CAEpF"}

package/dist/content-encryption-status.js

@@ -0,0 +1,158 @@
+/**
+ * WHY A SESSION HAS NO AGREED CONTENT KEY — `DOD-M15-EPHEMERAL-AUTH-1` (007-CRYPTO).
+ *
+ * ─── The rule, and it is deliberately absolute ─────────────────────────────────────────────────
+ *
+ * **A live message body is encrypted under the agreed session key, or it is not sent.** There is no
+ * degraded mode, no "unencrypted but visibly so", and no negotiation.
+ *
+ * That is not strictness for its own sake — it is what removes an entire class of defect. A
+ * fallback to plaintext is a thing an attacker steers a session into: strip the key frame, and a
+ * system that "carries on, visibly degraded" hands over exactly the plaintext the attacker wanted,
+ * while the operator sees a warning they have learned to scroll past. The salt can degrade because
+ * a missing salt costs a correlation property; a missing KEY costs the message.
+ *
+ * ⚠️ AND THERE IS NO COMPATIBILITY CASE TO SERVE. CELLO is pre-launch with no external installs, so
+ * "the counterparty is on a build that predates this" is not a state anything is in. Every reason
+ * below is a FAULT — local, transient, or a counterparty that did not complete an exchange it is
+ * running the code for. None of them is an accepted steady state, and none of them may be described
+ * to an operator as one.
+ *
+ * ─── Not the same question as the salt ─────────────────────────────────────────────────────────
+ *
+ * `content_hashes_salted` is about a relay CONFIRMING a guess at a stored hash. This is about a
+ * relay READING the message. A session can be salted and unencrypted; it cannot send while
+ * unencrypted.
+ *
+ * ─── Why a closed set and a total map ──────────────────────────────────────────────────────────
+ *
+ * Copied from `refusal-reasons.ts`, which exists because a free-form `reason: string` let a new code
+ * slip past every test in its own guard file. A `Record` over the union means a reason cannot be
+ * added without something for the reader to do about it.
+ */
+/**
+ * The `content_encryption` marker on a `content_frame`, naming the scheme its body is under.
+ *
+ * On the WIRE rather than inferred, so a receiver never has to guess a layout from a length — and
+ * ABSENT is refused rather than read as plaintext. There is no unencrypted sender to accommodate, so
+ * a missing marker is not "an old peer", it is a frame something rewrote.
+ */
+export const SESSION_CONTENT_ENCRYPTION_V1 = "session-aes-256-gcm-v1";
+export const CONTENT_ENCRYPTION_REASONS = {
+    /**
+     * The exchange has not finished yet. Transient, and the ordinary state for the instant between a
+     * session opening and its first connect completing.
+     */
+    NOT_YET_AGREED: "not_yet_agreed",
+    /**
+     * THIS machine has no identity key to sign its half with, so it cannot take part at all.
+     *
+     * Local setup fault — a signing-only or threshold provider, or an agent loaded without one. Named
+     * apart from the peer cases because "we could not sign" and "they did not answer" send the
+     * operator to opposite machines.
+     */
+    NO_LOCAL_IDENTITY: "no_local_identity",
+    /** THIS side's half never left the machine. Local and transient; the next connect re-announces. */
+    OUR_ANNOUNCE_FAILED: "our_announce_failed",
+    /**
+     * TERMINAL. The peer's key could not be tied to them and the session was stopped.
+     *
+     * ⚠️ THIS MUST SURVIVE THE TEARDOWN THAT FOLLOWS IT — review F2. The freeze destroys the session's
+     * key material, and clearing the reason with it left the listing recomputing `NOT_YET_AGREED`, so
+     * the one detection in this unit that means *someone may be substituting keys on your connection*
+     * reached the agent as "still agreeing, please wait". A security refusal that reads as a
+     * reassurance is worse than silence.
+     */
+    KEY_REFUSED: "key_refused",
+    /**
+     * The counterparty never sent their half.
+     *
+     * NOT "they are on an old build" — they are running this code. Something between the two of you
+     * dropped the frame, or their daemon is not answering.
+     */
+    PEER_SILENT: "peer_silent",
+};
+/**
+ * What the operator should DO. TOTAL over the union by construction.
+ *
+ * ⚠️ EVERY ENTRY NAMES A VERB THE READER CAN PERFORM, and none of them says "this is expected" —
+ * because none of these is. An affordance that resolves to nothing is worse than none, and a
+ * reassurance attached to a fault is worse than both.
+ */
+export const CONTENT_ENCRYPTION_GUIDANCE = {
+    [CONTENT_ENCRYPTION_REASONS.NOT_YET_AGREED]: "This session has not finished agreeing its encryption key with your counterparty, which happens " +
+        "as soon as you are both connected. A message sent before it completes is NOT held and is NOT " +
+        "sent in the open: it goes to your counterparty's relay mailbox instead, encrypted to their " +
+        "long-term key, and they receive it when they next collect. It arrives — it just takes the slow " +
+        "route, and that copy does not have the forward secrecy the direct path gives you. If this " +
+        "persists, your counterparty is not reachable right now.",
+    [CONTENT_ENCRYPTION_REASONS.NO_LOCAL_IDENTITY]: "THIS machine has no identity key available for this agent, so it cannot sign its half of the " +
+        "session encryption key — and every session it opens has the same problem. Your counterparty did " +
+        "nothing and does not need to change anything. Check that this agent was loaded with its identity " +
+        "key, then start a new session.",
+    [CONTENT_ENCRYPTION_REASONS.OUR_ANNOUNCE_FAILED]: "THIS side could not send its half of the session encryption key — the frame never left this " +
+        "machine, so your counterparty was never asked. Do not raise it with them. Look for " +
+        "session.key.announce.failed immediately above this line for the connection error; most often the " +
+        "direct link dropped between connecting and sending. It re-announces on the next connect.",
+    [CONTENT_ENCRYPTION_REASONS.KEY_REFUSED]: "STOPPED ON PURPOSE. The session encryption key your counterparty sent could not be tied to " +
+        "them, so this session was stopped rather than carried on in the open. The ordinary cause is a " +
+        "build mismatch. The one that matters is something between you substituting its own key so it " +
+        "can read what you send — which is exactly what this check exists to catch. Confirm with your " +
+        "counterparty OUT OF BAND, not over CELLO, before opening another session with them.",
+    [CONTENT_ENCRYPTION_REASONS.PEER_SILENT]: "Your counterparty never sent their half of the session encryption key. They are running the same " +
+        "protocol, so this is not a version difference — either the frame was dropped between you, or " +
+        "their daemon is not answering. Check they are online, then start a new session. Nothing was sent " +
+        "in the open in the meantime.",
+};
+/**
+ * ⚠️ **THE SAME REASONS, TOLD TO THE OTHER DIRECTION** — `029c` review F6.
+ *
+ * `CONTENT_ENCRYPTION_GUIDANCE` above is written for the SEND path: it explains what became of a
+ * message THIS operator tried to send. The inbound refusal (`no_session_key`) was reusing it
+ * verbatim, so an operator who could not open an INCOMING message read advice about their own
+ * outbound mail — *"A message sent before it completes … goes to your counterparty's relay
+ * mailbox"* — two directions and two mailboxes in one paragraph.
+ *
+ * The CAUSE is identical, so the reason set is shared; only the consequence differs, so only the
+ * prose is. Total over the union for the same reason the other map is: a new reason cannot be added
+ * without deciding what it means to the receiving side.
+ */
+export const CONTENT_ENCRYPTION_INBOUND_GUIDANCE = {
+    [CONTENT_ENCRYPTION_REASONS.NOT_YET_AGREED]: "This conversation had not finished agreeing its encryption key when their message arrived, " +
+        "which normally completes within a second of you both being connected. Nothing is wrong with " +
+        "their message or their build. If it keeps happening, one of you is not staying connected long " +
+        "enough for the exchange to finish.",
+    [CONTENT_ENCRYPTION_REASONS.NO_LOCAL_IDENTITY]: "THIS machine has no identity key available for this agent, so it cannot take part in the " +
+        "encryption exchange at all — and every conversation it opens has the same problem. Your " +
+        "counterparty did nothing and does not need to change anything. Check that this agent was " +
+        "loaded with its identity key, then start a new conversation.",
+    [CONTENT_ENCRYPTION_REASONS.OUR_ANNOUNCE_FAILED]: "THIS side never sent its half of the encryption key, so your counterparty could not finish the " +
+        "exchange and you cannot open what they sent. The fault is local — do not raise it with them. " +
+        "Look for session.key.announce.failed for the connection error; it re-announces on the next " +
+        "connect, so a new conversation usually clears it.",
+    [CONTENT_ENCRYPTION_REASONS.KEY_REFUSED]: "STOPPED ON PURPOSE. The encryption key your counterparty sent could not be tied to them, so " +
+        "this conversation was stopped rather than carried on in the open — which is why their message " +
+        "cannot be opened now. The ordinary cause is a build mismatch. The one that matters is " +
+        "something between you substituting its own key so it can read what you exchange. Confirm with " +
+        "them OUT OF BAND, not over CELLO, before opening another conversation.",
+    [CONTENT_ENCRYPTION_REASONS.PEER_SILENT]: "Your counterparty never sent their half of the encryption key, so there is nothing here to " +
+        "open their message with. They are running the same protocol, so this is not a version " +
+        "difference — either the frame was dropped between you, or their daemon is not answering. " +
+        "Check they are online, then start a new conversation.",
+};
+/**
+ * Render a reason for an agent.
+ *
+ * ⚠️ NO UNKNOWN-REASON FALLBACK, deliberately. The value is produced and consumed in one process
+ * from the closed set above — there is no column it is read back from and no other build writing
+ * one, so a "reason this version does not recognise" is a state nothing can be in. An earlier cut
+ * carried that branch anyway and described the value as coming off a database row, which was simply
+ * untrue. Unreachable defensive code that states a false provenance is worse than no code: it reads
+ * as a considered case and it is scaffolding for a world that does not exist.
+ *
+ * The map is TOTAL over the union, so the type is the check.
+ */
+export function contentEncryptionGuidanceFor(reason) {
+    return CONTENT_ENCRYPTION_GUIDANCE[reason];
+}
+//# sourceMappingURL=content-encryption-status.js.map

package/dist/content-encryption-status.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"content-encryption-status.js","sourceRoot":"","sources":["../src/content-encryption-status.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAEH;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,6BAA6B,GAAG,wBAAwB,CAAC;AAEtE,MAAM,CAAC,MAAM,0BAA0B,GAAG;IACxC;;;OAGG;IACH,cAAc,EAAE,gBAAgB;IAChC;;;;;;OAMG;IACH,iBAAiB,EAAE,mBAAmB;IACtC,mGAAmG;IACnG,mBAAmB,EAAE,qBAAqB;IAC1C;;;;;;;;OAQG;IACH,WAAW,EAAE,aAAa;IAC1B;;;;;OAKG;IACH,WAAW,EAAE,aAAa;CAClB,CAAC;AAKX;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,2BAA2B,GAA4C;IAClF,CAAC,0BAA0B,CAAC,cAAc,CAAC,EACzC,kGAAkG;QAClG,+FAA+F;QAC/F,6FAA6F;QAC7F,iGAAiG;QACjG,4FAA4F;QAC5F,yDAAyD;IAC3D,CAAC,0BAA0B,CAAC,iBAAiB,CAAC,EAC5C,+FAA+F;QAC/F,kGAAkG;QAClG,mGAAmG;QACnG,gCAAgC;IAClC,CAAC,0BAA0B,CAAC,mBAAmB,CAAC,EAC9C,8FAA8F;QAC9F,qFAAqF;QACrF,mGAAmG;QACnG,0FAA0F;IAC5F,CAAC,0BAA0B,CAAC,WAAW,CAAC,EACtC,6FAA6F;QAC7F,gGAAgG;QAChG,+FAA+F;QAC/F,+FAA+F;QAC/F,qFAAqF;IACvF,CAAC,0BAA0B,CAAC,WAAW,CAAC,EACtC,mGAAmG;QACnG,+FAA+F;QAC/F,mGAAmG;QACnG,8BAA8B;CACjC,CAAC;AAEF;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,MAAM,mCAAmC,GAA4C;IAC1F,CAAC,0BAA0B,CAAC,cAAc,CAAC,EACzC,6FAA6F;QAC7F,8FAA8F;QAC9F,gGAAgG;QAChG,oCAAoC;IACtC,CAAC,0BAA0B,CAAC,iBAAiB,CAAC,EAC5C,2FAA2F;QAC3F,0FAA0F;QAC1F,2FAA2F;QAC3F,8DAA8D;IAChE,CAAC,0BAA0B,CAAC,mBAAmB,CAAC,EAC9C,iGAAiG;QACjG,+FAA+F;QAC/F,6FAA6F;QAC7F,mDAAmD;IACrD,CAAC,0BAA0B,CAAC,WAAW,CAAC,EACtC,8FAA8F;QAC9F,gGAAgG;QAChG,wFAAwF;QACxF,gGAAgG;QAChG,wEAAwE;IAC1E,CAAC,0BAA0B,CAAC,WAAW,CAAC,EACtC,6FAA6F;QAC7F,wFAAwF;QACxF,2FAA2F;QAC3F,uDAAuD;CAC1D,CAAC;AAEF;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,4BAA4B,CAAC,MAA+B;IAC1E,OAAO,2BAA2B,CAAC,MAAM,CAAC,CAAC;AAC7C,CAAC"}

package/dist/content-park-client.d.ts

@@ -0,0 +1,90 @@
+import type { CelloNode } from "@cello-protocol/transport";
+import type { KeyProvider } from "@cello-protocol/crypto";
+import type { Logger } from "./types.js";
+/**
+ * DOD-M15-RELAYAUTH-1 review HIGH-3: the relay REFUSED to release parked content, as distinct from
+ * having none. Thrown rather than returned so it cannot be mistaken for an empty result — the whole
+ * defect was a refusal flattening into `[]`, which reads to an operator as "nothing was waiting".
+ */
+export declare class ContentParkRefusedError extends Error {
+    readonly reason: string;
+    constructor(reason: string);
+}
+/** One relay address `#open` tried to dial, and why that dial failed. */
+export interface ParkDialFailure {
+    addr: string;
+    error: string;
+}
+/**
+ * DOD-M15-PARKCONN-1 — the content-park stream could not be opened, WITH the reason there was
+ * nothing to open it on.
+ *
+ * `#open` dials before it opens a stream, and it used to discard every dial failure in an empty
+ * `catch`. That catch was the only place the reason for a missing connection ever existed, so an
+ * operator messaging an offline counterparty was told `No open connection to peer 12D3Koo…` — that
+ * there was no connection, never why — and the same action parked or failed with nothing to tell
+ * the two apart.
+ *
+ * A real `Error` (so `instanceof Error` and `extractErrorMessage` both work on it — the transport
+ * throws plain object literals, which stringify to "[object Object]") carrying the transport's own
+ * `reason` under the same field name the literal used, so existing `err.reason` readers are
+ * unaffected.
+ */
+export declare class ContentParkUnreachableError extends Error {
+    readonly reason: string;
+    readonly relayPeerId: string;
+    readonly dialFailures: readonly ParkDialFailure[];
+    constructor(args: {
+        reason: string;
+        relayPeerId: string;
+        dialFailures: readonly ParkDialFailure[];
+        cause: string;
+    });
+}
+/** A single parked entry returned by pull(). */
+export interface ParkedEntry {
+    contentHashHex: string;
+    sessionIdHex: string;
+    ciphertext: Uint8Array;
+}
+export interface ContentParkClientOptions {
+    /** Relay libp2p peer id (12D3Koo…) — from the session assignment's relay endpoint. */
+    relayPeerId: string;
+    /** Relay multiaddrs to dial. */
+    relayAddrs: string[];
+    logger: Logger;
+}
+export declare class ContentParkClient {
+    #private;
+    constructor(opts: ContentParkClientOptions);
+    /**
+     * Deposit ciphertext into the recipient's relay mailbox (sender side). Deposit is OPEN by
+     * design — the blob is E2E-encrypted to the recipient, so an unauthenticated deposit cannot
+     * leak plaintext.
+     */
+    deposit(node: CelloNode, args: {
+        recipientPubkey: Uint8Array;
+        contentHash: Uint8Array;
+        sessionId: Uint8Array;
+        ciphertext: Uint8Array;
+    }): Promise<{
+        ok: boolean;
+        reason?: string;
+        retryAfterMs?: number;
+    }>;
+    /**
+     * Pull the recipient's parked entries (recipient side). Runs the relay's auth challenge:
+     * sign buildContentParkAuthMsg(nonce, recipientPubkey) with the recipient's K_local to prove
+     * ownership before the relay releases anything.
+     */
+    pull(node: CelloNode, recipientPubkey: Uint8Array, signer: KeyProvider): Promise<ParkedEntry[]>;
+    /**
+     * Confirm-delete one parked entry (recipient side). The relay is delete-on-CONFIRM, not
+     * delete-on-pull, so without this the mailbox never drains and every reconnect re-pulls the whole
+     * history. Mirrors pull's I1 auth (sign buildContentParkAuthMsg(nonce, recipientPubkey)). Called
+     * after a parked entry is durably ingested. Best-effort: a failed confirm leaves the entry (it will
+     * be re-pulled + deduped next time, and the relay TTL eventually evicts it) — never loses content.
+     */
+    confirm(node: CelloNode, recipientPubkey: Uint8Array, contentHash: Uint8Array, signer: KeyProvider): Promise<boolean>;
+}
+//# sourceMappingURL=content-park-client.d.ts.map

package/dist/content-park-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"content-park-client.d.ts","sourceRoot":"","sources":["../src/content-park-client.ts"],"names":[],"mappings":"AA6BA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,2BAA2B,CAAC;AAC3D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAG1D,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,YAAY,CAAC;AAiBzC;;;;GAIG;AACH,qBAAa,uBAAwB,SAAQ,KAAK;IAChD,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;gBACZ,MAAM,EAAE,MAAM;CAK3B;AAED,yEAAyE;AACzE,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;CACf;AAED;;;;;;;;;;;;;;GAcG;AACH,qBAAa,2BAA4B,SAAQ,KAAK;IACpD,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,YAAY,EAAE,SAAS,eAAe,EAAE,CAAC;gBAEtC,IAAI,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,CAAC;QAAC,YAAY,EAAE,SAAS,eAAe,EAAE,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE;CAUnH;AAED,gDAAgD;AAChD,MAAM,WAAW,WAAW;IAC1B,cAAc,EAAE,MAAM,CAAC;IACvB,YAAY,EAAE,MAAM,CAAC;IACrB,UAAU,EAAE,UAAU,CAAC;CACxB;AAED,MAAM,WAAW,wBAAwB;IACvC,sFAAsF;IACtF,WAAW,EAAE,MAAM,CAAC;IACpB,gCAAgC;IAChC,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,qBAAa,iBAAiB;;gBAKhB,IAAI,EAAE,wBAAwB;IAM1C;;;;OAIG;IACG,OAAO,CACX,IAAI,EAAE,SAAS,EACf,IAAI,EAAE;QAAE,eAAe,EAAE,UAAU,CAAC;QAAC,WAAW,EAAE,UAAU,CAAC;QAAC,SAAS,EAAE,UAAU,CAAC;QAAC,UAAU,EAAE,UAAU,CAAA;KAAE,GAC5G,OAAO,CAAC;QAAE,EAAE,EAAE,OAAO,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,YAAY,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IA8CnE;;;;OAIG;IACG,IAAI,CAAC,IAAI,EAAE,SAAS,EAAE,eAAe,EAAE,UAAU,EAAE,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC;IAiFrG;;;;;;OAMG;IACG,OAAO,CAAC,IAAI,EAAE,SAAS,EAAE,eAAe,EAAE,UAAU,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,OAAO,CAAC;CA2I5H"}