seam

Import

Import

import * as api from "@fungi.computer/seam";

Exports

Kind	Export	Description
Cclass	SeamReplayGuard	Bounded process-local history; deliberately not durable across reconstruction.
Ttype alias	SeamSigner	Sender identity and private Ed25519 key used to sign seam requests.
Ttype alias	SeamVerifiers	Receiver-pinned public Ed25519 verification keys, indexed by sender key ID.
Ttype alias	SeamReplayAdmission	An atomic admission decision; refusal never discards still-live history.
Ttype alias	SeamReplayRecord	Seam supplies the retention deadline, inclusive of its last fresh instant.
Ttype alias	SeamReplayStore	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.
constconstant	seamHeader	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.
constconstant	unsignedPayload	Digest sentinel for a body whose integrity is supplied by its transport.
fnfunction	importSeamSigner()	keyId:base64(pkcs8), the form a Worker secret or key file holds.
fnfunction	importSeamVerifiers()	{ keyId: base64(raw 32-byte public key) }, the pinned peers.
fnfunction	seamBodyDigest()	The body digest to sign: SHA-256 hex of buffered bytes, or unsigned.
fnfunction	signSeamRequest()	The x-fungi-seam header value for one request.
fnfunction	verifySeamRequest()	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.

SeamReplayGuardCclass

Bounded process-local history; deliberately not durable across reconstruction.

Implements

• SeamReplayStore

Constructors

Constructor

Signature

new SeamReplayGuard(): SeamReplayGuard;

Returns

SeamReplayGuard

Methods

admit()

Signature

admit(__namedParameters): SeamReplayAdmission;

Record one nonce, refusing capacity rather than evicting live history.

Parameters

Parameter	Type
__namedParameters	SeamReplayRecord

Returns

SeamReplayAdmission

Implementation of

Signature

SeamReplayStore.admit;

SeamSignerTtype alias

Signature

type SeamSigner = Readonly<{
  keyId: string;
  key: CryptoKey;
}>;

Sender identity and private Ed25519 key used to sign seam requests.

---

SeamVerifiersTtype alias

Signature

type SeamVerifiers = ReadonlyMap<string, CryptoKey>;

Receiver-pinned public Ed25519 verification keys, indexed by sender key ID.

---

SeamReplayAdmissionTtype alias

Signature

type SeamReplayAdmission =
  "admitted" | "replayed" | "at-capacity" | "unavailable";

An atomic admission decision; refusal never discards still-live history.

---

SeamReplayRecordTtype alias

Signature

type SeamReplayRecord = Readonly<{
  nonce: string;
  now: number;
  expiresAt: number;
}>;

Seam supplies the retention deadline, inclusive of its last fresh instant.

---

SeamReplayStoreTtype alias

Signature

type SeamReplayStore = Readonly<{
  admit: (record) => SeamReplayAdmission | Promise<SeamReplayAdmission>;
}>;

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.

seamHeaderconstconstant

Signature

const seamHeader: "x-fungi-seam" = "x-fungi-seam";

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.

---

unsignedPayloadconstconstant

Signature

const unsignedPayload: "UNSIGNED-PAYLOAD" = "UNSIGNED-PAYLOAD";

Digest sentinel for a body whose integrity is supplied by its transport.

importSeamSigner()fnfunction

Signature

function importSeamSigner(secret): Promise<
  Readonly<{
    keyId: string;
    key: CryptoKey;
  }>
>;

keyId:base64(pkcs8), the form a Worker secret or key file holds.

Parameters

Parameter	Type
secret	string

Returns

Promise<Readonly<{ keyId: string; key: CryptoKey; }>>

---

importSeamVerifiers()fnfunction

Signature

function importSeamVerifiers(publicKeys): Promise<SeamVerifiers>;

{ keyId: base64(raw 32-byte public key) }, the pinned peers.

Parameters

Parameter	Type
publicKeys	Readonly<Record<string, string>>

Returns

Promise<SeamVerifiers>

---

seamBodyDigest()fnfunction

Signature

function seamBodyDigest(body): Promise<string>;

The body digest to sign: SHA-256 hex of buffered bytes, or unsigned.

Parameters

Parameter	Type
body	ArrayBuffer | Uint8Array<ArrayBuffer> | null

Returns

Promise<string>

---

signSeamRequest()fnfunction

Signature

function signSeamRequest(
  signer,
  audience,
  method,
  url,
  digest,
  now?,
): Promise<string>;

The x-fungi-seam header value for one request.

Parameters

Parameter	Type
signer	SeamSigner
audience	string
method	string
url	string
digest	string
now	number

Returns

Promise<string>

---

verifySeamRequest()fnfunction

Signature

function verifySeamRequest(
  verifiers,
  audience,
  method,
  url,
  header,
  digest,
  replay,
  now?,
): Promise<string>;

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.

Parameters

Parameter	Type
verifiers	SeamVerifiers
audience	string
method	string
url	string
header	string | null
digest	string | null
replay	SeamReplayStore
now	number

Returns

Promise<string>