@lumenflow/packs-sidekick 4.24.0 → 5.0.1

package/dist/src/adapters/control-plane-bridge.adapter.js

@@ -0,0 +1,263 @@
+// Copyright (c) 2026 Hellmai Ltd
+// SPDX-License-Identifier: AGPL-3.0-only
+/**
+ * WU-2737 (INIT-060 WU-7b, ADR-013 §ChannelBridge):
+ * Control-plane ChannelBridge adapter.
+ *
+ * Cloud-backed implementation of the ChannelBridge port. Codes directly
+ * against the contract published in
+ * `docs/operations/coordination/channel-bridge-cloud-stub.md` (WU-2736):
+ *
+ *   POST /api/v1/workspaces/{workspace_id}/sidekick/channel
+ *
+ * Responsibilities:
+ *   - Outbound `send()` POSTs each envelope with `Bearer <enrollment_token>`.
+ *   - At-least-once delivery scoped by `(channel_id, envelope.id)` dedup key;
+ *     safe to replay on transport failure (cloud returns `deduped: true`).
+ *   - Backpressure split (ADR-013 §4):
+ *       - `kind: "ephemeral"` fails silently on 5xx / 429 / network errors
+ *         (no outbox, no retry, no elevated logging).
+ *       - `kind: "queue"` parks in the local outbox on any non-2xx and drains
+ *         FIFO on reconnect / explicit `flush()` / `disconnect()`.
+ *   - Inbound `receive()` drains a loopback-friendly poll endpoint. The stub
+ *     contract (WU-2736) does not yet freeze the inbound wire shape; the
+ *     adapter exposes `pollIntervalMs` + a minimal GET fetcher so a mock
+ *     server or future coord-stub-signed inbound path can plug in without
+ *     changing the port.
+ *   - `register()` is idempotent on BridgeConfig identity (deterministic id
+ *     from provider/name/options hash — matches the filesystem adapter pattern).
+ *   - `disconnect()` flushes queued envelopes before resolving; subsequent
+ *     `send()` on the same channel id rejects (port contract).
+ */
+import { createHash } from 'node:crypto';
+import { setTimeout as delay } from 'node:timers/promises';
+import { CloudOutbox } from './cloud-queue.js';
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+const DEFAULT_POLL_INTERVAL_MS = 1000;
+const QUEUED_REASON = 'queued_for_replay';
+const DROPPED_EPHEMERAL_REASON = 'dropped_ephemeral';
+const INVALID_ENVELOPE_REASON = 'invalid_envelope';
+const DISCONNECTED_REASON = 'disconnected';
+function hashOptions(options) {
+    const payload = JSON.stringify(options ?? {}, Object.keys(options ?? {}).sort());
+    return createHash('sha256').update(payload).digest('hex').slice(0, 16);
+}
+function mintChannelId(config) {
+    const payload = `${config.provider}::${config.name}::${hashOptions(config.options)}`;
+    const digest = createHash('sha256').update(payload).digest('hex').slice(0, 24);
+    return `chan-${digest}`;
+}
+function safeParseJson(text) {
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return null;
+    }
+}
+// ---------------------------------------------------------------------------
+// Adapter factory
+// ---------------------------------------------------------------------------
+export function createControlPlaneChannelBridge(options) {
+    const baseUrl = options.baseUrl.replace(/\/+$/, '');
+    const workspaceId = options.workspaceId;
+    const tokenProvider = options.tokenProvider;
+    const outbox = new CloudOutbox(options.outboxDir);
+    const pollIntervalMs = options.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS;
+    const fetchImpl = options.fetchImpl ?? fetch;
+    const registry = new Map();
+    const disconnected = new Set();
+    function postUrl() {
+        return `${baseUrl}/api/v1/workspaces/${encodeURIComponent(workspaceId)}/sidekick/channel`;
+    }
+    function inboundUrl(channelId) {
+        return `${postUrl()}?channel_id=${encodeURIComponent(channelId)}`;
+    }
+    async function authHeaders() {
+        const token = await tokenProvider();
+        return {
+            'Content-Type': 'application/json',
+            Authorization: `Bearer ${token}`,
+        };
+    }
+    async function postOnce(channelId, envelope) {
+        let response;
+        try {
+            response = await fetchImpl(postUrl(), {
+                method: 'POST',
+                headers: await authHeaders(),
+                body: JSON.stringify({ channel_id: channelId, envelope }),
+            });
+        }
+        catch (error) {
+            return { kind: 'network_error', cause: error };
+        }
+        const text = await response.text();
+        if (response.ok) {
+            const body = safeParseJson(text) ?? {};
+            return { kind: 'accepted', body };
+        }
+        const errorBody = safeParseJson(text) ?? {};
+        const retryAfterHeader = response.headers.get('retry-after');
+        const retryAfterSeconds = retryAfterHeader ? Number.parseInt(retryAfterHeader, 10) : undefined;
+        // 4xx non-retryable per contract §Error Response Shape — everything
+        // other than 429 is a correctness bug / auth failure we don't retry.
+        if (response.status >= 400 && response.status < 500 && response.status !== 429) {
+            return { kind: 'non_retryable', status: response.status, error: errorBody.error };
+        }
+        return {
+            kind: 'retryable',
+            status: response.status,
+            error: errorBody.error,
+            retryAfterSeconds: Number.isFinite(retryAfterSeconds) ? retryAfterSeconds : undefined,
+        };
+    }
+    function nonRetryableReason(error) {
+        // Contract codes map 1:1 onto SendResult.reason for observability. Unknown
+        // codes collapse into a stable catch-all so audit logs stay readable.
+        const code = error?.code;
+        if (code === 'invalid_envelope')
+            return INVALID_ENVELOPE_REASON;
+        if (code)
+            return code;
+        return 'rejected_non_retryable';
+    }
+    async function drainOutbox() {
+        const pending = await outbox.list();
+        for (const record of pending) {
+            // Cast: outbox entries are keyed by the same branded ids we minted.
+            const cid = record.channel_id;
+            const outcome = await postOnce(cid, record.envelope);
+            if (outcome.kind === 'accepted') {
+                await outbox.remove(record._filename);
+                continue;
+            }
+            if (outcome.kind === 'non_retryable') {
+                // Correctness bug on a parked envelope — drop it so the outbox does
+                // not grow unbounded on permanent errors (matches contract table:
+                // `invalid_envelope` / `workspace_mismatch` are log-and-drop).
+                await outbox.remove(record._filename);
+                continue;
+            }
+            // Retryable / network error — stop the drain; caller retries later.
+            return;
+        }
+    }
+    async function sendInternal(channelId, envelope) {
+        // Opportunistic drain: a successful path clears any previous parked
+        // envelopes before the new one POSTs, preserving FIFO order under the
+        // "replay-on-reconnect" rule (§4).
+        if (envelope.kind === 'queue') {
+            await drainOutbox();
+        }
+        const outcome = await postOnce(channelId, envelope);
+        if (outcome.kind === 'accepted') {
+            const body = outcome.body;
+            const result = {
+                accepted: body.accepted ?? true,
+            };
+            if (body.delivery_id !== undefined) {
+                result.delivery_id = body.delivery_id;
+            }
+            if (body.deduped === true) {
+                result.deduped = true;
+            }
+            if (body.reason !== undefined) {
+                result.reason = body.reason;
+            }
+            return result;
+        }
+        if (outcome.kind === 'non_retryable') {
+            // Both kinds: log-and-drop per §Error Response Shape.
+            return {
+                accepted: false,
+                reason: nonRetryableReason(outcome.error),
+            };
+        }
+        // Retryable (5xx / 429) OR network error: split by envelope.kind.
+        if (envelope.kind === 'ephemeral') {
+            // Fail-silent per §4; no outbox, no throw.
+            return { accepted: false, reason: DROPPED_EPHEMERAL_REASON };
+        }
+        // queue: park for replay.
+        await outbox.enqueue(channelId, envelope);
+        return { accepted: false, reason: QUEUED_REASON };
+    }
+    // -------------------------------------------------------------------------
+    // Port methods
+    // -------------------------------------------------------------------------
+    return {
+        async register(bridgeConfig) {
+            const key = `${bridgeConfig.provider}::${bridgeConfig.name}::${hashOptions(bridgeConfig.options)}`;
+            const existing = registry.get(key);
+            if (existing) {
+                return existing;
+            }
+            const id = mintChannelId(bridgeConfig);
+            registry.set(key, id);
+            return id;
+        },
+        async send(channelId, envelope) {
+            if (disconnected.has(channelId)) {
+                throw new Error(`ControlPlaneChannelBridge: channel ${channelId} is disconnected; send rejected (reason=${DISCONNECTED_REASON}).`);
+            }
+            return sendInternal(channelId, envelope);
+        },
+        async *receive(channelId) {
+            // Poll-based inbound. One pass drains whatever is currently queued on
+            // the cloud side; the loop continues until `disconnect()` flips the
+            // flag so the iterator terminates without hanging (port contract).
+            while (!disconnected.has(channelId)) {
+                let response;
+                try {
+                    response = await fetchImpl(inboundUrl(channelId), {
+                        method: 'GET',
+                        headers: await authHeaders(),
+                    });
+                }
+                catch {
+                    // Transient network error — back off and retry.
+                    await delay(pollIntervalMs);
+                    continue;
+                }
+                if (!response.ok) {
+                    // 4xx/5xx on poll: back off. Errors here do NOT terminate the
+                    // iterator; the port contract treats the iterator as long-lived
+                    // until `disconnect()`.
+                    await delay(pollIntervalMs);
+                    continue;
+                }
+                const text = await response.text();
+                const body = safeParseJson(text) ?? {};
+                const envelopes = body.envelopes ?? [];
+                for (const env of envelopes) {
+                    if (disconnected.has(channelId)) {
+                        return;
+                    }
+                    yield env;
+                }
+                if (envelopes.length === 0) {
+                    await delay(pollIntervalMs);
+                }
+            }
+        },
+        async disconnect(channelId) {
+            // Flush outbox before closing so queued envelopes for any channel have
+            // a chance to drain (port contract: "queued envelopes flush before
+            // this resolves").
+            try {
+                await drainOutbox();
+            }
+            catch {
+                // Drain best-effort; disconnect must always resolve.
+            }
+            disconnected.add(channelId);
+        },
+        async flush() {
+            await drainOutbox();
+        },
+    };
+}
+//# sourceMappingURL=control-plane-bridge.adapter.js.map

package/dist/src/adapters/control-plane-bridge.adapter.js.map

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

package/dist/src/adapters/filesystem-bridge.adapter.d.ts

@@ -0,0 +1,11 @@
+import type { ChannelBridge } from '../ports/channel-bridge.port.js';
+export interface FilesystemChannelBridgeOptions {
+    /**
+     * Directory under which the bridge materialises channel state. Tests set
+     * this to a tmpdir; in production the caller passes
+     * `.lumenflow/state/packs/sidekick/` (or equivalent per ADR-013).
+     */
+    rootDir: string;
+}
+export declare function createFilesystemChannelBridge(options: FilesystemChannelBridgeOptions): ChannelBridge;
+//# sourceMappingURL=filesystem-bridge.adapter.d.ts.map

package/dist/src/adapters/filesystem-bridge.adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"filesystem-bridge.adapter.d.ts","sourceRoot":"","sources":["../../../src/adapters/filesystem-bridge.adapter.ts"],"names":[],"mappings":"AAmCA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,iCAAiC,CAAC;AAMrE,MAAM,WAAW,8BAA8B;IAC7C;;;;OAIG;IACH,OAAO,EAAE,MAAM,CAAC;CACjB;AAoFD,wBAAgB,6BAA6B,CAC3C,OAAO,EAAE,8BAA8B,GACtC,aAAa,CAyFf"}

package/dist/src/adapters/filesystem-bridge.adapter.js

@@ -0,0 +1,161 @@
+// Copyright (c) 2026 Hellmai Ltd
+// SPDX-License-Identifier: AGPL-3.0-only
+/**
+ * WU-2735 (INIT-060 WU-7a, ADR-013 §ChannelBridge):
+ * Filesystem implementation of the ChannelBridge port.
+ *
+ * Backing layout:
+ *
+ *   <rootDir>/channels/<channel-id>/envelopes.jsonl
+ *   <rootDir>/channels/<channel-id>/config.json
+ *   <rootDir>/registry.json       (BridgeConfig identity → ChannelId)
+ *
+ * Writes are atomic: a new envelope is written to a per-pid tmp file and
+ * `rename(2)`'d on top of a sibling, then append to the JSONL via
+ * `appendFile` with `O_APPEND` semantics (Node delegates to the kernel, which
+ * guarantees single-write atomicity for writes below PIPE_BUF; our JSON lines
+ * sit well below that for realistic envelopes and we additionally bound the
+ * write under a per-channel in-process mutex).
+ *
+ * The adapter is deliberately minimal: the sidekick pack's transport registry
+ * (`channel-transports.ts`) remains the runtime dispatch path for the existing
+ * `channel:send` tool; WU-2735 lands the port/adapter skeleton only.
+ */
+import { createHash } from 'node:crypto';
+import { appendFile, mkdir, readFile, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+const REGISTRY_FILENAME = 'registry.json';
+const CHANNELS_SUBDIR = 'channels';
+const ENVELOPES_FILENAME = 'envelopes.jsonl';
+const CONFIG_FILENAME = 'config.json';
+function hashOptions(options) {
+    const payload = JSON.stringify(options ?? {}, Object.keys(options ?? {}).sort());
+    return createHash('sha256').update(payload).digest('hex').slice(0, 16);
+}
+function mintChannelId(config) {
+    // Deterministic id per (provider, name, options) — stable across bridge
+    // instances backed by the same rootDir so `register` is idempotent even on
+    // cold start without reading the registry.
+    const payload = `${config.provider}::${config.name}::${hashOptions(config.options)}`;
+    const digest = createHash('sha256').update(payload).digest('hex').slice(0, 24);
+    return `chan-${digest}`;
+}
+async function readRegistry(registryPath) {
+    try {
+        const raw = await readFile(registryPath, 'utf8');
+        return JSON.parse(raw);
+    }
+    catch (error) {
+        const err = error;
+        if (err.code === 'ENOENT') {
+            return { entries: [] };
+        }
+        throw error;
+    }
+}
+async function writeRegistryAtomic(registryPath, registry) {
+    await mkdir(path.dirname(registryPath), { recursive: true });
+    const tmpPath = `${registryPath}.tmp-${process.pid}-${Date.now()}`;
+    await writeFile(tmpPath, JSON.stringify(registry, null, 2), 'utf8');
+    const { rename } = await import('node:fs/promises');
+    await rename(tmpPath, registryPath);
+}
+// Per-bridge-instance lock map so concurrent send() calls on a single channel
+// serialise their appends. Filesystem atomicity still holds under crash, but
+// the mutex ensures emit order is preserved (ADR-013 §3).
+function createLockGate() {
+    const chains = new Map();
+    return {
+        async withLock(key, fn) {
+            const previous = chains.get(key) ?? Promise.resolve();
+            const next = previous.then(fn, fn);
+            chains.set(key, next.then(() => undefined, () => undefined));
+            return next;
+        },
+    };
+}
+// ---------------------------------------------------------------------------
+// Adapter factory
+// ---------------------------------------------------------------------------
+export function createFilesystemChannelBridge(options) {
+    const rootDir = path.resolve(options.rootDir);
+    const registryPath = path.join(rootDir, REGISTRY_FILENAME);
+    const lockGate = createLockGate();
+    const disconnected = new Set();
+    function channelDir(id) {
+        return path.join(rootDir, CHANNELS_SUBDIR, id);
+    }
+    async function ensureRegistered(config) {
+        const registry = await readRegistry(registryPath);
+        const id = mintChannelId(config);
+        const optionsHash = hashOptions(config.options);
+        const existing = registry.entries.find((entry) => entry.id === id);
+        if (existing) {
+            return existing.id;
+        }
+        registry.entries.push({
+            id,
+            provider: config.provider,
+            name: config.name,
+            options_hash: optionsHash,
+        });
+        await writeRegistryAtomic(registryPath, registry);
+        const dir = channelDir(id);
+        await mkdir(dir, { recursive: true });
+        await writeFile(path.join(dir, CONFIG_FILENAME), JSON.stringify({ provider: config.provider, name: config.name }, null, 2), 'utf8');
+        return id;
+    }
+    async function assertActive(channelId) {
+        if (disconnected.has(channelId)) {
+            throw new Error(`ChannelBridge: channel ${channelId} is disconnected; send rejected.`);
+        }
+        const registry = await readRegistry(registryPath);
+        if (!registry.entries.some((entry) => entry.id === channelId)) {
+            throw new Error(`ChannelBridge: channel ${channelId} is not registered.`);
+        }
+    }
+    return {
+        async register(bridgeConfig) {
+            return ensureRegistered(bridgeConfig);
+        },
+        async send(channelId, envelope) {
+            await assertActive(channelId);
+            const envelopesPath = path.join(channelDir(channelId), ENVELOPES_FILENAME);
+            await lockGate.withLock(channelId, async () => {
+                await mkdir(path.dirname(envelopesPath), { recursive: true });
+                await appendFile(envelopesPath, `${JSON.stringify(envelope)}\n`, 'utf8');
+            });
+            return { accepted: true, delivery_id: envelope.id };
+        },
+        async *receive(channelId) {
+            if (disconnected.has(channelId)) {
+                return;
+            }
+            const envelopesPath = path.join(channelDir(channelId), ENVELOPES_FILENAME);
+            let raw;
+            try {
+                raw = await readFile(envelopesPath, 'utf8');
+            }
+            catch (error) {
+                const err = error;
+                if (err.code === 'ENOENT') {
+                    return;
+                }
+                throw error;
+            }
+            for (const line of raw.split('\n')) {
+                if (line.length === 0) {
+                    continue;
+                }
+                yield JSON.parse(line);
+            }
+        },
+        async disconnect(channelId) {
+            disconnected.add(channelId);
+        },
+    };
+}
+//# sourceMappingURL=filesystem-bridge.adapter.js.map

package/dist/src/adapters/filesystem-bridge.adapter.js.map

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

package/dist/src/channel-ingress.d.ts

@@ -0,0 +1,46 @@
+declare const ENVELOPE_FROM_SOURCE_TOKEN: "token";
+export interface PhoneChannelIngressInput {
+    /**
+     * Raw request body as parsed from JSON. Opaque record; the sanitizer does
+     * not inspect `body`, only the `from` attribution fields.
+     */
+    body: Readonly<Record<string, unknown>>;
+    /**
+     * Authoritative identity claim resolved from the bearer token. Required:
+     * without a token subject, cloud cannot attribute the message, and the
+     * ingress path rejects the request.
+     */
+    authoritativeFrom: string;
+}
+export interface PhoneChannelIngressEnvelope {
+    /**
+     * Sanitised request body with any body-level `from` stripped. Everything
+     * else the caller supplied is preserved so downstream code (channel.send,
+     * routing) can consume arbitrary payload fields.
+     */
+    body: Record<string, unknown>;
+    /** Authoritative attribution string (`{workspace_id}:phone:{device_id}`). */
+    from: string;
+    /** Always `'token'` — cloud-safe invariant per ADR-013 §5. */
+    from_source: typeof ENVELOPE_FROM_SOURCE_TOKEN;
+}
+export declare class PhoneChannelIngressError extends Error {
+    readonly statusCode: number;
+    constructor(message: string, statusCode: number);
+}
+/**
+ * Sanitize an inbound phone-channel request. Returns a cleaned envelope with
+ * the authoritative `from` baked in. Throws `PhoneChannelIngressError` (HTTP
+ * 400) when the authoritative `from` is missing — the surface translates the
+ * error to a 400/403 response.
+ */
+export declare function sanitizePhoneChannelIngress(input: PhoneChannelIngressInput): PhoneChannelIngressEnvelope;
+/**
+ * Convenience: reports whether the given `from` subject matches the
+ * phone-device grammar (`{workspace_id}:phone:{device_id}`). Useful to
+ * tell workspace-scoped actors from phone-device actors in the audit log
+ * without reaching for the enrollment parser.
+ */
+export declare function isPhoneSubject(subject: string): boolean;
+export {};
+//# sourceMappingURL=channel-ingress.d.ts.map

package/dist/src/channel-ingress.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"channel-ingress.d.ts","sourceRoot":"","sources":["../../src/channel-ingress.ts"],"names":[],"mappings":"AAyBA,QAAA,MAAM,0BAA0B,EAAG,OAAgB,CAAC;AAEpD,MAAM,WAAW,wBAAwB;IACvC;;;OAGG;IACH,IAAI,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IACxC;;;;OAIG;IACH,iBAAiB,EAAE,MAAM,CAAC;CAC3B;AAED,MAAM,WAAW,2BAA2B;IAC1C;;;;OAIG;IACH,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC9B,6EAA6E;IAC7E,IAAI,EAAE,MAAM,CAAC;IACb,8DAA8D;IAC9D,WAAW,EAAE,OAAO,0BAA0B,CAAC;CAChD;AAED,qBAAa,wBAAyB,SAAQ,KAAK;IACjD,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;gBAEhB,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM;CAKhD;AAED;;;;;GAKG;AACH,wBAAgB,2BAA2B,CACzC,KAAK,EAAE,wBAAwB,GAC9B,2BAA2B,CA2B7B;AAkBD;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAavD"}

package/dist/src/channel-ingress.js

@@ -0,0 +1,90 @@
+// Copyright (c) 2026 Hellmai Ltd
+// SPDX-License-Identifier: AGPL-3.0-only
+/**
+ * WU-2731 (INIT-060 phase 3, ADR-013 §5 Identity):
+ * Pure inbound-channel ingress sanitizer.
+ *
+ * ADR-013 §5 rules, enforced here:
+ *
+ * - The authoritative `from` value for an inbound phone POST comes from the
+ *   authenticated token subject (`{workspace_id}:phone:{device_id}`). Cloud
+ *   MUST NOT trust a `from` field supplied in the request body.
+ *
+ * - Body-supplied `from` (and any alias under `metadata.from`) is stripped
+ *   before the envelope reaches domain code. The surface that calls this
+ *   module is expected to pass the resolved `from` separately; attempting to
+ *   ingest a body-only envelope (no authoritative from) fails closed.
+ *
+ * The module is HTTP-independent: both the kernel tool-api surface and the
+ * future control-plane adapter (WU-2737) call the same sanitizer so the
+ * ignore-body-from rule is enforced in one place.
+ */
+const ENVELOPE_BODY_FIELD_FROM = 'from';
+const ENVELOPE_METADATA_KEY = 'metadata';
+const ENVELOPE_FROM_SOURCE_TOKEN = 'token';
+export class PhoneChannelIngressError extends Error {
+    statusCode;
+    constructor(message, statusCode) {
+        super(message);
+        this.name = 'PhoneChannelIngressError';
+        this.statusCode = statusCode;
+    }
+}
+/**
+ * Sanitize an inbound phone-channel request. Returns a cleaned envelope with
+ * the authoritative `from` baked in. Throws `PhoneChannelIngressError` (HTTP
+ * 400) when the authoritative `from` is missing — the surface translates the
+ * error to a 400/403 response.
+ */
+export function sanitizePhoneChannelIngress(input) {
+    if (typeof input.authoritativeFrom !== 'string' || input.authoritativeFrom.length === 0) {
+        throw new PhoneChannelIngressError('Inbound phone channel requires authoritative from (token subject); body-only attribution is rejected.', 400);
+    }
+    const sanitizedBody = stripKey(input.body, ENVELOPE_BODY_FIELD_FROM);
+    const rawMetadata = sanitizedBody[ENVELOPE_METADATA_KEY];
+    if (rawMetadata !== null &&
+        typeof rawMetadata === 'object' &&
+        !Array.isArray(rawMetadata) &&
+        ENVELOPE_BODY_FIELD_FROM in rawMetadata) {
+        sanitizedBody[ENVELOPE_METADATA_KEY] = stripKey(rawMetadata, ENVELOPE_BODY_FIELD_FROM);
+    }
+    return {
+        body: sanitizedBody,
+        from: input.authoritativeFrom,
+        from_source: ENVELOPE_FROM_SOURCE_TOKEN,
+    };
+}
+/**
+ * Copy `record` omitting the given key. Implemented with a filtered
+ * `Object.entries` rather than `delete` to satisfy the linter's ban on
+ * dynamic-delete (which would otherwise be a no-op for literal keys but
+ * fails the rule uniformly).
+ */
+function stripKey(record, key) {
+    const result = {};
+    for (const [entryKey, entryValue] of Object.entries(record)) {
+        if (entryKey !== key) {
+            result[entryKey] = entryValue;
+        }
+    }
+    return result;
+}
+/**
+ * Convenience: reports whether the given `from` subject matches the
+ * phone-device grammar (`{workspace_id}:phone:{device_id}`). Useful to
+ * tell workspace-scoped actors from phone-device actors in the audit log
+ * without reaching for the enrollment parser.
+ */
+export function isPhoneSubject(subject) {
+    const parts = subject.split(':');
+    if (parts.length !== 3) {
+        return false;
+    }
+    const [workspace, kind, device] = parts;
+    return (kind === 'phone' &&
+        typeof workspace === 'string' &&
+        workspace.length > 0 &&
+        typeof device === 'string' &&
+        device.length > 0);
+}
+//# sourceMappingURL=channel-ingress.js.map

package/dist/src/channel-ingress.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"channel-ingress.js","sourceRoot":"","sources":["../../src/channel-ingress.ts"],"names":[],"mappings":"AAAA,iCAAiC;AACjC,yCAAyC;AAEzC;;;;;;;;;;;;;;;;;;GAkBG;AAEH,MAAM,wBAAwB,GAAG,MAAe,CAAC;AACjD,MAAM,qBAAqB,GAAG,UAAmB,CAAC;AAClD,MAAM,0BAA0B,GAAG,OAAgB,CAAC;AA6BpD,MAAM,OAAO,wBAAyB,SAAQ,KAAK;IACxC,UAAU,CAAS;IAE5B,YAAY,OAAe,EAAE,UAAkB;QAC7C,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,0BAA0B,CAAC;QACvC,IAAI,CAAC,UAAU,GAAG,UAAU,CAAC;IAC/B,CAAC;CACF;AAED;;;;;GAKG;AACH,MAAM,UAAU,2BAA2B,CACzC,KAA+B;IAE/B,IAAI,OAAO,KAAK,CAAC,iBAAiB,KAAK,QAAQ,IAAI,KAAK,CAAC,iBAAiB,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACxF,MAAM,IAAI,wBAAwB,CAChC,uGAAuG,EACvG,GAAG,CACJ,CAAC;IACJ,CAAC;IAED,MAAM,aAAa,GAAG,QAAQ,CAAC,KAAK,CAAC,IAAI,EAAE,wBAAwB,CAAC,CAAC;IACrE,MAAM,WAAW,GAAG,aAAa,CAAC,qBAAqB,CAAC,CAAC;IACzD,IACE,WAAW,KAAK,IAAI;QACpB,OAAO,WAAW,KAAK,QAAQ;QAC/B,CAAC,KAAK,CAAC,OAAO,CAAC,WAAW,CAAC;QAC3B,wBAAwB,IAAK,WAAuC,EACpE,CAAC;QACD,aAAa,CAAC,qBAAqB,CAAC,GAAG,QAAQ,CAC7C,WAAsC,EACtC,wBAAwB,CACzB,CAAC;IACJ,CAAC;IAED,OAAO;QACL,IAAI,EAAE,aAAa;QACnB,IAAI,EAAE,KAAK,CAAC,iBAAiB;QAC7B,WAAW,EAAE,0BAA0B;KACxC,CAAC;AACJ,CAAC;AAED;;;;;GAKG;AACH,SAAS,QAAQ,CAAC,MAAyC,EAAE,GAAW;IACtE,MAAM,MAAM,GAA4B,EAAE,CAAC;IAC3C,KAAK,MAAM,CAAC,QAAQ,EAAE,UAAU,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;QAC5D,IAAI,QAAQ,KAAK,GAAG,EAAE,CAAC;YACrB,MAAM,CAAC,QAAQ,CAAC,GAAG,UAAU,CAAC;QAChC,CAAC;IACH,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,cAAc,CAAC,OAAe;IAC5C,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IACjC,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACvB,OAAO,KAAK,CAAC;IACf,CAAC;IACD,MAAM,CAAC,SAAS,EAAE,IAAI,EAAE,MAAM,CAAC,GAAG,KAAK,CAAC;IACxC,OAAO,CACL,IAAI,KAAK,OAAO;QAChB,OAAO,SAAS,KAAK,QAAQ;QAC7B,SAAS,CAAC,MAAM,GAAG,CAAC;QACpB,OAAO,MAAM,KAAK,QAAQ;QAC1B,MAAM,CAAC,MAAM,GAAG,CAAC,CAClB,CAAC;AACJ,CAAC"}