@fungi.computer/seam 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jamstack Consulting LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,79 @@
-# Temporary Holding Version
+# Fungi host seam
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Owns the Ed25519 request authentication protocol between the Hub and its on-box
+hosts. Consumers import `@fungi.computer/seam`. The moved implementation and
+replay/signature tests retain their original behavior. Keys remain with the
+operator; no keys are stored in this package. The package ships the protocol and
+replay guard; hosts own key provisioning.
+
+`@fungi.computer/seam/machine-link-protocol` owns the shared machine-link
+audience/dial URL, bounded read/leave and Agent-operation grammar, Agent mail
+address schema, and `createMachineLinkPostChannel`. The channel carries ordinary
+Carrier Post envelopes and receipts; Carrier retains retries. Hosts own live
+authorization, socket lifetime and durable replay storage. Delegation request
+keys and execution policy remain with the delegation engine, not Seam.
+
+Run `pnpm --filter @fungi.computer/seam test` for signature, audience, body and
+replay laws. Computer and game-server host tests exercise its real consumers.
+
+## Packed consumer readiness
+
+Run `pnpm run build`, `pnpm run pack` and `pnpm run stranger` in this package.
+The maintained stranger proof installs only package tarballs into a fresh npm
+consumer, checks the exact shipped files, runs the public runtime fixture and
+compiles every JavaScript entrypoint with strict NodeNext and no library-check
+skip. This qualification does not publish npm releases or push a repository
+split.
+
+See [LICENSE](LICENSE) for the license and the package manifest for its public
+repository destination.
+
+## Quick start
+
+```ts
+import { SeamReplayGuard } from "@fungi.computer/seam";
+
+const replay = new SeamReplayGuard();
+const now = Date.now();
+const record = {
+  nonce: "00112233445566778899aabbccddeeff",
+  now,
+  expiresAt: now + 120_000,
+};
+console.log(replay.admit(record)); // admitted
+console.log(replay.admit(record)); // replayed
+```
+
+## Core concepts
+
+The sender signs method, audience, path, timestamp, nonce and payload digest.
+The receiver checks the signature, freshness and replay guard against its pinned
+keys.
+
+`verifySeamRequest` accepts one `SeamReplayStore`. It verifies the signature
+before awaiting atomic admission, and supplies a deadline covering the complete
+freshness window, including its last instant. The store must preserve that
+deadline, record before reporting success, and refuse at its finite capacity
+rather than evict still-live nonces. Its closed decisions are `admitted`,
+`replayed`, `at-capacity`, and `unavailable`; all refusals fail verification.
+
+`SeamReplayGuard` is the process-local implementation, with a private
+10,000-record ceiling. It is not persistent. A durable receiver must bind one
+store to its reconstruction-stable receiver namespace; storage and numeric
+capacity are host implementation decisions. There is no memory fallback on
+persistence failure. A record remains live when `expiresAt === now`; prune only
+strictly older deadlines, without assuming insertion order is expiry order.
+
+## Examples and checks
+
+The packed runtime fixture at `test/stranger/runtime.mjs` exercises the public
+API in a fresh consumer. Run `pnpm run stranger` after building the package.
+
+## Install
+
+Install the package tarball with npm. The manifest pins its runtime
+dependencies.
+
+## Contribute and license
+
+See [LICENSE](LICENSE) for the MIT terms.

package/dist/index.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Mutual authentication for on-box host seams: every request in either
+ * direction is signed with Ed25519 by its sender and verified against a
+ * public key the receiver pins.
+ *
+ * - Down: the Hub signs with the platform seam key; the host pins its public key.
+ * - Up: the host signs reports with its host key; the Hub pins it in the host registry.
+ *
+ * The signature covers an audience (so a request meant for one side cannot
+ * be replayed at the other), the method, path and query, a timestamp, a
+ * nonce and the body digest. Streaming bodies (forwarded guest traffic,
+ * port previews, WebSocket upgrades) sign `UNSIGNED-PAYLOAD` and rely on the
+ * TLS transport (Cloudflare Tunnel) for body integrity. Receivers reject a
+ * timestamp outside the skew window and a nonce seen within it. Private keys
+ * stay with their owner; projections and registries carry public data only.
+ *
+ * This module is plain Web Crypto so the Worker and the Node.js host share it.
+ */
+export declare const seamHeader = "x-fungi-seam";
+/** Digest sentinel for a body whose integrity is supplied by its transport. */
+export declare const unsignedPayload = "UNSIGNED-PAYLOAD";
+/** Sender identity and private Ed25519 key used to sign seam requests. */
+export type SeamSigner = Readonly<{
+    /** Key identifier included in the signed bytes and the request header. */
+    keyId: string;
+    /** Private Ed25519 key with signing usage; custody stays with the sender. */
+    key: CryptoKey;
+}>;
+/** Receiver-pinned public Ed25519 verification keys, indexed by sender key ID. */
+export type SeamVerifiers = ReadonlyMap<string, CryptoKey>;
+/** `keyId:base64(pkcs8)`, the form a Worker secret or key file holds. */
+export declare function importSeamSigner(secret: string): Promise<SeamSigner>;
+/** `{ keyId: base64(raw 32-byte public key) }`, the pinned peers. */
+export declare function importSeamVerifiers(publicKeys: Readonly<Record<string, string>>): Promise<SeamVerifiers>;
+/** The body digest to sign: SHA-256 hex of buffered bytes, or unsigned. */
+export declare function seamBodyDigest(body: ArrayBuffer | Uint8Array<ArrayBuffer> | null): Promise<string>;
+/** The `x-fungi-seam` header value for one request. */
+export declare function signSeamRequest(signer: SeamSigner, audience: string, method: string, url: string, digest: string, now?: number): Promise<string>;
+/** An atomic admission decision; refusal never discards still-live history. */
+export type SeamReplayAdmission = "admitted" | "replayed" | "at-capacity" | "unavailable";
+/** Seam supplies the retention deadline, inclusive of its last fresh instant. */
+export type SeamReplayRecord = Readonly<{
+    /** Authenticated request nonce, unique within this logical receiver's history. */
+    nonce: string;
+    /** Receiver's current time in Unix epoch milliseconds. */
+    now: number;
+    /**
+     * Inclusive retention deadline in Unix epoch milliseconds.
+     * Prune only when this deadline is strictly earlier than `now`.
+     */
+    expiresAt: number;
+}>;
+/**
+ * One logical receiver's bounded replay history. A durable host must reopen
+ * the same receiver namespace after reconstruction, never fall back to memory.
+ * Admission atomically prunes expired records, checks nonce uniqueness and the
+ * implementation's finite capacity, then records the nonce before answering
+ * `admitted`. Persist before success; never shorten Seam's inclusive deadline.
+ * Storage mechanics and the numeric capacity belong to the implementation.
+ */
+export type SeamReplayStore = Readonly<{
+    /** Atomically admit one nonce or refuse it; commit before reporting admission. */
+    admit: (record: SeamReplayRecord) => SeamReplayAdmission | Promise<SeamReplayAdmission>;
+}>;
+/** Bounded process-local history; deliberately not durable across reconstruction. */
+export declare class SeamReplayGuard implements SeamReplayStore {
+    #private;
+    /** Record one nonce, refusing capacity rather than evicting live history. */
+    admit({ nonce, now, expiresAt }: SeamReplayRecord): SeamReplayAdmission;
+}
+/**
+ * Verify one request's seam header. `digest` is the receiver's own digest of
+ * the buffered body, or `null` when the route accepts an unsigned stream.
+ * Answers the sender's key id.
+ */
+export declare function verifySeamRequest(verifiers: SeamVerifiers, audience: string, method: string, url: string, header: string | null, digest: string | null, replay: SeamReplayStore, now?: number): Promise<string>;

package/dist/index.js

@@ -0,0 +1,217 @@
+/**
+ * Mutual authentication for on-box host seams: every request in either
+ * direction is signed with Ed25519 by its sender and verified against a
+ * public key the receiver pins.
+ *
+ * - Down: the Hub signs with the platform seam key; the host pins its public key.
+ * - Up: the host signs reports with its host key; the Hub pins it in the host registry.
+ *
+ * The signature covers an audience (so a request meant for one side cannot
+ * be replayed at the other), the method, path and query, a timestamp, a
+ * nonce and the body digest. Streaming bodies (forwarded guest traffic,
+ * port previews, WebSocket upgrades) sign `UNSIGNED-PAYLOAD` and rely on the
+ * TLS transport (Cloudflare Tunnel) for body integrity. Receivers reject a
+ * timestamp outside the skew window and a nonce seen within it. Private keys
+ * stay with their owner; projections and registries carry public data only.
+ *
+ * This module is plain Web Crypto so the Worker and the Node.js host share it.
+ */
+export const seamHeader = "x-fungi-seam";
+/** Digest sentinel for a body whose integrity is supplied by its transport. */
+export const unsignedPayload = "UNSIGNED-PAYLOAD";
+const version = "fungi-seam-v1";
+const maximumSkewMs = 60_000;
+const maximumNonces = 10_000;
+class SeamAuthError extends Error {
+    constructor(reason) {
+        super(`Seam request rejected: ${reason}`);
+        this.name = "SeamAuthError";
+    }
+}
+const keyIdPattern = /^[a-z0-9][a-z0-9._-]{0,63}$/;
+const noncePattern = /^[0-9a-f]{32}$/;
+const digestPattern = /^([0-9a-f]{64}|UNSIGNED-PAYLOAD)$/;
+const signaturePattern = /^[A-Za-z0-9_-]{86}$/;
+function bytesFromBase64(value) {
+    const binary = atob(value);
+    const bytes = new Uint8Array(binary.length);
+    for (let index = 0; index < binary.length; index += 1)
+        bytes[index] = binary.charCodeAt(index);
+    return bytes;
+}
+function base64url(bytes) {
+    let binary = "";
+    for (const byte of new Uint8Array(bytes))
+        binary += String.fromCharCode(byte);
+    return btoa(binary)
+        .replaceAll("+", "-")
+        .replaceAll("/", "_")
+        .replace(/=+$/, "");
+}
+function bytesFromBase64url(value) {
+    const padded = value.replaceAll("-", "+").replaceAll("_", "/");
+    return bytesFromBase64(padded + "=".repeat((4 - (padded.length % 4)) % 4));
+}
+function hex(bytes) {
+    return Array.from(new Uint8Array(bytes), (byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+/** `keyId:base64(pkcs8)`, the form a Worker secret or key file holds. */
+export async function importSeamSigner(secret) {
+    const at = secret.indexOf(":");
+    const keyId = secret.slice(0, at);
+    if (at < 1 || !keyIdPattern.test(keyId))
+        throw new SeamAuthError("the signing key has no valid key id");
+    const key = await crypto.subtle.importKey("pkcs8", bytesFromBase64(secret.slice(at + 1)), { name: "Ed25519" }, false, ["sign"]);
+    return { keyId, key };
+}
+/** `{ keyId: base64(raw 32-byte public key) }`, the pinned peers. */
+export async function importSeamVerifiers(publicKeys) {
+    const verifiers = new Map();
+    for (const [keyId, raw] of Object.entries(publicKeys)) {
+        if (!keyIdPattern.test(keyId))
+            throw new SeamAuthError(`invalid pinned key id ${keyId}`);
+        verifiers.set(keyId, await crypto.subtle.importKey("raw", bytesFromBase64(raw), { name: "Ed25519" }, false, ["verify"]));
+    }
+    return verifiers;
+}
+/** The body digest to sign: SHA-256 hex of buffered bytes, or unsigned. */
+export async function seamBodyDigest(body) {
+    if (body === null)
+        return unsignedPayload;
+    return hex(await crypto.subtle.digest("SHA-256", body));
+}
+function canonical(audience, keyId, method, pathAndQuery, timestamp, nonce, digest) {
+    // A copy, so the bytes sit in a plain ArrayBuffer Web Crypto accepts.
+    return new Uint8Array(new TextEncoder().encode([
+        version,
+        audience,
+        keyId,
+        method.toUpperCase(),
+        pathAndQuery,
+        String(timestamp),
+        nonce,
+        digest,
+    ].join("\n")));
+}
+function pathAndQueryOf(url) {
+    const parsed = new URL(url);
+    return `${parsed.pathname}${parsed.search}`;
+}
+/** The `x-fungi-seam` header value for one request. */
+export async function signSeamRequest(signer, audience, method, url, digest, now = Date.now()) {
+    const nonceBytes = new Uint8Array(16);
+    crypto.getRandomValues(nonceBytes);
+    const nonce = hex(nonceBytes.buffer);
+    const signature = await crypto.subtle.sign({ name: "Ed25519" }, signer.key, canonical(audience, signer.keyId, method, pathAndQueryOf(url), now, nonce, digest));
+    return `v1 key=${signer.keyId} ts=${String(now)} nonce=${nonce} body=${digest} sig=${base64url(signature)}`;
+}
+/** Bounded process-local history; deliberately not durable across reconstruction. */
+export class SeamReplayGuard {
+    #seen = new Map();
+    /** Record one nonce, refusing capacity rather than evicting live history. */
+    admit({ nonce, now, expiresAt }) {
+        this.#prune(now);
+        if (this.#seen.has(nonce))
+            return "replayed";
+        if (this.#seen.size >= maximumNonces)
+            return "at-capacity";
+        this.#seen.set(nonce, expiresAt);
+        return "admitted";
+    }
+    #prune(now) {
+        for (const [seen, expires] of this.#seen) {
+            // Freshness accepts the boundary instant. Clock steps also mean Map
+            // insertion order need not be expiry order: inspect every bounded entry.
+            if (expires < now)
+                this.#seen.delete(seen);
+        }
+    }
+}
+function seamFields(value) {
+    const fields = new Map();
+    const parts = (value ?? "").split(" ");
+    if (parts[0] !== "v1")
+        throw new SeamAuthError("missing or unknown version");
+    for (const part of parts.slice(1)) {
+        const [name, field] = seamField(part);
+        fields.set(name, field);
+    }
+    return fields;
+}
+function seamField(part) {
+    const at = part.indexOf("=");
+    if (at < 1)
+        throw new SeamAuthError("malformed header");
+    return [part.slice(0, at), part.slice(at + 1)];
+}
+function requiredField(fields, name) {
+    return fields.get(name) ?? "";
+}
+function parseSeamHeader(value) {
+    const fields = seamFields(value);
+    const parsed = {
+        keyId: requiredField(fields, "key"),
+        timestamp: Number(fields.get("ts")),
+        nonce: requiredField(fields, "nonce"),
+        digest: requiredField(fields, "body"),
+        signature: requiredField(fields, "sig"),
+    };
+    if (fields.size !== 5 || !validSeamHeader(parsed))
+        throw new SeamAuthError("malformed header");
+    return parsed;
+}
+function validSeamHeader(header) {
+    return [
+        keyIdPattern.test(header.keyId),
+        Number.isSafeInteger(header.timestamp),
+        noncePattern.test(header.nonce),
+        digestPattern.test(header.digest),
+        signaturePattern.test(header.signature),
+    ].every(Boolean);
+}
+/**
+ * Verify one request's seam header. `digest` is the receiver's own digest of
+ * the buffered body, or `null` when the route accepts an unsigned stream.
+ * Answers the sender's key id.
+ */
+export async function verifySeamRequest(verifiers, audience, method, url, header, digest, replay, now = Date.now()) {
+    const parsed = parseSeamHeader(header);
+    const key = verifiers.get(parsed.keyId);
+    if (key === undefined)
+        throw new SeamAuthError("unknown key");
+    assertSeamFreshness(parsed, digest, now);
+    const valid = await crypto.subtle.verify({ name: "Ed25519" }, key, bytesFromBase64url(parsed.signature), canonical(audience, parsed.keyId, method, pathAndQueryOf(url), parsed.timestamp, parsed.nonce, parsed.digest));
+    if (!valid)
+        throw new SeamAuthError("bad signature");
+    const admission = await replay.admit({
+        nonce: parsed.nonce,
+        now,
+        // A timestamp first admitted at ts-skew remains fresh through ts+skew.
+        expiresAt: now + 2 * maximumSkewMs,
+    });
+    switch (admission) {
+        case "admitted":
+            return parsed.keyId;
+        case "replayed":
+            throw new SeamAuthError("replayed nonce");
+        case "at-capacity":
+            throw new SeamAuthError("replay capacity reached");
+        case "unavailable":
+            throw new SeamAuthError("replay store unavailable");
+        default:
+            throw new SeamAuthError("replay store unavailable");
+    }
+}
+function assertSeamFreshness(parsed, digest, now) {
+    if (Math.abs(now - parsed.timestamp) > maximumSkewMs)
+        throw new SeamAuthError("timestamp outside the skew window");
+    assertSeamDigest(parsed.digest, digest);
+}
+function assertSeamDigest(signed, digest) {
+    const expected = digest ?? unsignedPayload;
+    if (signed === expected)
+        return;
+    throw new SeamAuthError(digest === null
+        ? "route takes an unsigned stream only"
+        : "body digest mismatch");
+}

package/dist/machine-link-post.d.ts

@@ -0,0 +1,38 @@
+import { type PostDeliveryResult, type PostEnvelope } from "@fungi.computer/carrier/post";
+declare const MachineLinkPostUnavailable_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
+    readonly _tag: "MachineLinkPostUnavailable";
+} & Readonly<A>;
+/** No receiver receipt was obtained. Carrier, not Seam, retains retries. */
+export declare class MachineLinkPostUnavailable extends MachineLinkPostUnavailable_base<{
+    /** Transient transport failure; none of these asserts command refusal. */
+    readonly reason: "closed" | "busy" | "timed_out" | "send_failed";
+    /** The native send failure, when the platform supplied one. */
+    readonly cause?: unknown;
+}> {
+}
+/**
+ * One connection's bounded Post I/O, without an outbox, dedupe store or RPC
+ * capability table. Native socket ownership and authentication stay with the
+ * host. Reconstruct after hibernation when idle; close on disconnect/restart
+ * and let the existing Carrier outbox retry the same frozen envelope.
+ *
+ * Receipt payloads remain opaque. The Agent mail route still requires a real
+ * Shiitake Accepted receipt; a generic Post acknowledgment is not one.
+ */
+export declare function createMachineLinkPostChannel(options: {
+    send: (frame: string) => void | Promise<void>;
+    receive: (envelope: PostEnvelope) => Promise<PostDeliveryResult>;
+    limits: {
+        maxInFlight: number;
+        maxFrameBytes: number;
+        acknowledgmentMs: number;
+    };
+}): {
+    /** Send now; never acknowledge custody before the receiver replies. */
+    deliver: (envelope: PostEnvelope) => Promise<PostDeliveryResult>;
+    /** Called only for a host-authenticated, current native socket. */
+    receive: (text: string) => Promise<void>;
+    /** Forget only pending I/O. The durable sender still owns undelivered work. */
+    close: () => void;
+};
+export {};

package/dist/machine-link-post.js

@@ -0,0 +1,129 @@
+import * as Data from "effect/Data";
+import * as Schema from "effect/Schema";
+import { PostDeliveryResultSchema, PostEnvelopeSchema, } from "@fungi.computer/carrier/post";
+const identitySchema = Schema.Struct({
+    key: PostEnvelopeSchema.fields.key,
+    kind: PostEnvelopeSchema.fields.kind,
+    address: PostEnvelopeSchema.fields.address,
+});
+const frameSchema = Schema.Union([
+    Schema.Struct({
+        type: Schema.Literal("post"),
+        envelope: PostEnvelopeSchema,
+    }),
+    Schema.Struct({
+        type: Schema.Literal("receipt"),
+        identity: identitySchema,
+        result: PostDeliveryResultSchema,
+    }),
+]);
+const positiveInteger = Schema.Int.check(Schema.isGreaterThanOrEqualTo(1), Schema.isLessThanOrEqualTo(Number.MAX_SAFE_INTEGER));
+const limitsSchema = Schema.Struct({
+    maxInFlight: positiveInteger,
+    maxFrameBytes: positiveInteger,
+    acknowledgmentMs: Schema.Int.check(Schema.isGreaterThanOrEqualTo(1), 
+    // The maintained platform timer cannot represent a larger delay.
+    Schema.isLessThanOrEqualTo(2_147_483_647)),
+});
+/** No receiver receipt was obtained. Carrier, not Seam, retains retries. */
+export class MachineLinkPostUnavailable extends Data.TaggedError("MachineLinkPostUnavailable") {
+}
+function identity(envelope) {
+    return {
+        key: envelope.key,
+        kind: envelope.kind,
+        address: envelope.address,
+    };
+}
+/**
+ * One connection's bounded Post I/O, without an outbox, dedupe store or RPC
+ * capability table. Native socket ownership and authentication stay with the
+ * host. Reconstruct after hibernation when idle; close on disconnect/restart
+ * and let the existing Carrier outbox retry the same frozen envelope.
+ *
+ * Receipt payloads remain opaque. The Agent mail route still requires a real
+ * Shiitake Accepted receipt; a generic Post acknowledgment is not one.
+ */
+export function createMachineLinkPostChannel(options) {
+    const limits = Schema.decodeUnknownSync(limitsSchema)(options.limits);
+    const decode = Schema.decodeUnknownSync(Schema.fromJsonString(frameSchema), {
+        onExcessProperty: "error",
+    });
+    const pending = new Map();
+    let closed = false;
+    let receiving = 0;
+    function checkSize(text) {
+        if (new TextEncoder().encode(text).byteLength > limits.maxFrameBytes)
+            throw new RangeError("Machine link Post frame exceeds its byte ceiling");
+    }
+    async function send(text) {
+        if (closed)
+            throw new MachineLinkPostUnavailable({ reason: "closed" });
+        checkSize(text);
+        await options.send(text);
+    }
+    function take(key) {
+        const entry = pending.get(key);
+        if (entry !== undefined) {
+            pending.delete(key);
+            clearTimeout(entry.timer);
+        }
+        return entry;
+    }
+    return {
+        /** Send now; never acknowledge custody before the receiver replies. */
+        deliver: async (envelope) => {
+            if (closed)
+                throw new MachineLinkPostUnavailable({ reason: "closed" });
+            const key = JSON.stringify(identity(envelope));
+            if (pending.has(key) || pending.size >= limits.maxInFlight)
+                throw new MachineLinkPostUnavailable({ reason: "busy" });
+            const text = JSON.stringify({ type: "post", envelope });
+            checkSize(text);
+            return new Promise((resolve, reject) => {
+                const timer = setTimeout(() => {
+                    take(key)?.reject(new MachineLinkPostUnavailable({ reason: "timed_out" }));
+                }, limits.acknowledgmentMs);
+                pending.set(key, { resolve, reject, timer });
+                void send(text).catch((cause) => {
+                    take(key)?.reject(new MachineLinkPostUnavailable({
+                        reason: "send_failed",
+                        cause,
+                    }));
+                });
+            });
+        },
+        /** Called only for a host-authenticated, current native socket. */
+        receive: async (text) => {
+            if (closed)
+                throw new MachineLinkPostUnavailable({ reason: "closed" });
+            checkSize(text);
+            const frame = decode(text);
+            if (frame.type === "receipt") {
+                // Late receipts cannot create custody or a future successful send.
+                take(JSON.stringify(identity(frame.identity)))?.resolve(frame.result);
+                return;
+            }
+            if (receiving >= limits.maxInFlight)
+                throw new MachineLinkPostUnavailable({ reason: "busy" });
+            receiving += 1;
+            try {
+                const result = Schema.decodeUnknownSync(PostDeliveryResultSchema)(await options.receive(frame.envelope));
+                await send(JSON.stringify({
+                    type: "receipt",
+                    identity: identity(frame.envelope),
+                    result,
+                }));
+            }
+            finally {
+                receiving -= 1;
+            }
+        },
+        /** Forget only pending I/O. The durable sender still owns undelivered work. */
+        close: () => {
+            closed = true;
+            for (const key of pending.keys())
+                take(key)?.reject(new MachineLinkPostUnavailable({ reason: "closed" }));
+        },
+    };
+}

package/dist/machine-link-protocol.d.ts

@@ -0,0 +1,86 @@
+import * as Schema from "effect/Schema";
+export { createMachineLinkPostChannel, MachineLinkPostUnavailable, } from "./machine-link-post.js";
+/** Shared signature audience; neither names nor private Local selectors enter it. */
+export declare function machineLinkAudience(teamId: string, deviceId: string): string;
+/** The exact GET path signed by Local and verified by its receiving link. */
+export declare function machineLinkDialUrl(issuer: string, teamId: string, deviceId: string): URL;
+/** Post destination only; delegation keys and admission belong to their engine. */
+export type AgentMailAddress = {
+    /** Owning Team or standalone scope, a nonempty identity of at most 256 characters. */
+    readonly scopeId: string;
+    /** Destination Agent, a nonempty identity of at most 256 characters. */
+    readonly agentId: string;
+};
+/** Maintained decoder for the shared Post address, not delegation authority. */
+export declare const agentMailAddressSchema: Schema.Codec<AgentMailAddress>;
+/** Idempotent Session creation requested through an authorized machine link. */
+export type MachineAgentCreateSession = {
+    /** Finite operation discriminator. */
+    readonly type: "createSession";
+    /** Caller-owned creation intent, a nonempty identity of at most 256 characters. */
+    readonly requestId: string;
+};
+/** Read the destination owner's outcome for one previously accepted command. */
+export type MachineAgentSettlement = {
+    /** Finite operation discriminator. */
+    readonly type: "settlement";
+    /** Requesting Agent; the receiver still checks its relationship to the command. */
+    readonly requesterAgentId: string;
+    /** Recipient Session identity, nonempty and at most 256 characters. */
+    readonly sessionId: string;
+    /** Original Accepted command identity, nonempty and at most 256 characters. */
+    readonly commandId: string;
+};
+/** Finite Agent operations, not an arbitrary HTTP/RPC tunnel. */
+export type MachineAgentOperation = MachineAgentCreateSession | MachineAgentSettlement;
+/** Decode operation grammar without granting access to an Agent or Session. */
+export declare const machineAgentOperationSchema: Schema.Codec<MachineAgentOperation>;
+/** An operation plus its host-derived caller, still subject to receiver admission. */
+export type MachineAgentRequest = {
+    /** Calling Agent identity; syntax alone never authenticates this field. */
+    readonly actorAgentId: string;
+    /** The finite operation to admit at the destination. */
+    readonly operation: MachineAgentOperation;
+};
+/** Decode the request representation, not caller authority. */
+export declare const machineAgentRequestSchema: Schema.Codec<MachineAgentRequest>;
+/** One public Agent directory entry, without a private Local selector or path. */
+export type MachineDirectoryAgent = {
+    /** Team Agent identity, nonempty and at most 256 characters. */
+    readonly agentId: string;
+    /** Display label of at most 256 characters. */
+    readonly name: string;
+};
+/** Bounded directory representation sent by an enrolled machine. */
+export type MachineDirectory = {
+    /** At most 256 public Agent entries; the host checks their enrollment. */
+    readonly agents: readonly MachineDirectoryAgent[];
+};
+/** Decode the bounded directory representation without admitting its entries. */
+export declare const machineDirectorySchema: Schema.Codec<MachineDirectory>;
+/** Ask the owner to remove one enrolled Team Agent projection. */
+export type MachineLinkLeaveFrame = {
+    /** Finite control discriminator. */
+    readonly type: "leave";
+    /** Team Agent identity, nonempty and at most 256 characters. */
+    readonly agentId: string;
+};
+/** Read one bounded transcript page through the Session owner's ordinary cursor. */
+export type MachineLinkReadFrame = {
+    /** Finite control discriminator. */
+    readonly type: "read";
+    /** Correlation identity, nonempty and at most 256 characters. */
+    readonly requestId: string;
+    /** Team Agent identity, nonempty and at most 256 characters. */
+    readonly agentId: string;
+    /** Session identity, nonempty and at most 256 characters. */
+    readonly sessionId: string;
+    /** Opaque older-page cursor from Session.read(), not a transport stream cursor. */
+    readonly before?: string;
+    /** Integer page bound from one through 64. */
+    readonly limit: number;
+};
+/** Non-mail requests, not authenticated membership or admitted Session access. */
+export type MachineLinkControlFrame = MachineLinkLeaveFrame | MachineLinkReadFrame;
+/** Decode JSON only; the host still owns device, member and Agent admission. */
+export declare function decodeMachineLinkControlFrame(text: string): MachineLinkControlFrame;

package/dist/machine-link-protocol.js

@@ -0,0 +1,63 @@
+import * as Schema from "effect/Schema";
+export { createMachineLinkPostChannel, MachineLinkPostUnavailable, } from "./machine-link-post.js";
+/** Shared signature audience; neither names nor private Local selectors enter it. */
+export function machineLinkAudience(teamId, deviceId) {
+    return `fungi-machine-link:${teamId}:${deviceId}`;
+}
+/** The exact GET path signed by Local and verified by its receiving link. */
+export function machineLinkDialUrl(issuer, teamId, deviceId) {
+    return new URL(`/api/teams/${encodeURIComponent(teamId)}/local/mesh/${encodeURIComponent(deviceId)}/connect`, issuer);
+}
+const identitySchema = Schema.String.check(Schema.isMinLength(1), Schema.isMaxLength(256));
+/** Maintained decoder for the shared Post address, not delegation authority. */
+export const agentMailAddressSchema = Schema.Struct({
+    scopeId: identitySchema,
+    agentId: identitySchema,
+});
+/** Decode operation grammar without granting access to an Agent or Session. */
+export const machineAgentOperationSchema = Schema.Union([
+    Schema.Struct({
+        type: Schema.Literal("createSession"),
+        requestId: identitySchema,
+    }),
+    Schema.Struct({
+        type: Schema.Literal("settlement"),
+        requesterAgentId: identitySchema,
+        sessionId: identitySchema,
+        commandId: identitySchema,
+    }),
+]);
+/** Decode the request representation, not caller authority. */
+export const machineAgentRequestSchema = Schema.Struct({
+    actorAgentId: identitySchema,
+    operation: machineAgentOperationSchema,
+});
+/** Decode the bounded directory representation without admitting its entries. */
+export const machineDirectorySchema = Schema.Struct({
+    agents: Schema.Array(Schema.Struct({
+        agentId: identitySchema,
+        name: Schema.String.check(Schema.isMaxLength(256)),
+    })).check(Schema.isMaxLength(256)),
+});
+const leaveFrameSchema = Schema.Struct({
+    type: Schema.Literal("leave"),
+    agentId: identitySchema,
+});
+const readFrameSchema = Schema.Struct({
+    type: Schema.Literal("read"),
+    requestId: identitySchema,
+    agentId: identitySchema,
+    sessionId: identitySchema,
+    // Session.read() pages before its opaque oldestCursor, not after a stream.
+    before: Schema.optionalKey(Schema.String),
+    limit: Schema.Int.check(Schema.isGreaterThanOrEqualTo(1), Schema.isLessThanOrEqualTo(64)),
+});
+const controlFrameSchema = Schema.Union([leaveFrameSchema, readFrameSchema]);
+/** Decode JSON only; the host still owns device, member and Agent admission. */
+export function decodeMachineLinkControlFrame(text) {
+    if (new TextEncoder().encode(text).byteLength > 512 * 1024)
+        throw new RangeError("Machine link frame exceeds 512 KiB");
+    return Schema.decodeUnknownSync(Schema.fromJsonString(controlFrameSchema), {
+        onExcessProperty: "error",
+    })(text);
+}

package/package.json

@@ -1,6 +1,32 @@
 {
   "name": "@fungi.computer/seam",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "author": "Levi <levi@technomancy.dev>",
+  "private": false,
+  "description": "Ed25519 authentication between Fungi Hub and on-box hosts",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./machine-link-protocol": {
+      "types": "./dist/machine-link-protocol.d.ts",
+      "import": "./dist/machine-link-protocol.js"
+    }
+  },
+  "dependencies": {
+    "@fungi.computer/carrier": "0.1.0",
+    "effect": "4.0.2"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/fungi-computer/seam.git"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ]
 }