@fungi.computer/seam 0.0.0-stage → 0.0.1

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,53 @@
-# 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.
+
+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();
+console.log(replay.admit("00112233445566778899aabbccddeeff", now));
+console.log(replay.admit("00112233445566778899aabbccddeeff", now));
+```
+
+## 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.
+
+## 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,45 @@
+/**
+ * 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";
+export declare const unsignedPayload = "UNSIGNED-PAYLOAD";
+export type SeamSigner = Readonly<{
+    keyId: string;
+    key: CryptoKey;
+}>;
+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>;
+/** Nonces seen inside the skew window, bounded. */
+export declare class SeamReplayGuard {
+    #private;
+    /** Record `nonce`; false if it was already seen and is still live. */
+    admit(nonce: string, now: number): 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 declare function verifySeamRequest(verifiers: SeamVerifiers, audience: string, method: string, url: string, header: string | null, digest: string | null, replay: SeamReplayGuard, now?: number): Promise<string>;

package/dist/index.js

@@ -0,0 +1,206 @@
+/**
+ * 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";
+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)}`;
+}
+/** Nonces seen inside the skew window, bounded. */
+export class SeamReplayGuard {
+    #seen = new Map();
+    /** Record `nonce`; false if it was already seen and is still live. */
+    admit(nonce, now) {
+        this.#prune(now);
+        if (this.#seen.has(nonce))
+            return false;
+        this.#makeRoom();
+        this.#seen.set(nonce, now + 2 * maximumSkewMs);
+        return true;
+    }
+    #prune(now) {
+        for (const [seen, expires] of this.#seen) {
+            if (expires > now)
+                break;
+            this.#seen.delete(seen);
+        }
+    }
+    #makeRoom() {
+        if (this.#seen.size < maximumNonces)
+            return;
+        const oldest = this.#seen.keys().next();
+        if (!oldest.done)
+            this.#seen.delete(oldest.value);
+    }
+}
+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");
+    if (!replay.admit(parsed.nonce, now))
+        throw new SeamAuthError("replayed nonce");
+    return parsed.keyId;
+}
+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/package.json

@@ -1,6 +1,25 @@
 {
   "name": "@fungi.computer/seam",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.0.1",
+  "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"
+    }
+  },
+  "dependencies": {},
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/fungi-computer/seam.git"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ]
 }