@byollm/relay 0.1.0-alpha.10

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Of Tomorrow, Inc.
+
+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

@@ -0,0 +1,136 @@
+> [!WARNING]
+> **Alpha (`0.1.0-alpha.10`) — under active development. Don't use this yet.**
+>
+> This is a walking skeleton. It routes real jobs between real daemons and real
+> sites, and it is the fixture byollm_009 freezes against — but it keeps its
+> state in memory, serves one site, and has never run anywhere but a test.
+
+# `@byollm/relay`
+
+The **reference relay**: it routes byollm jobs between a site and someone's
+machine while holding no key that can open either end's traffic.
+
+```
+  site ──stub──▶  relay  ◀──claim── daemon
+       ◀─who claimed?─┤
+       ──sealed payload─▶ ──────────▶ (opened only on the device)
+       ◀────────────── sealed result ◀──
+```
+
+## Why a relay can be blind
+
+A payload is encrypted to the machine that runs it. Nobody knows which machine
+that is until one claims the job — so the site publishes a **stub** first
+(byollm_009 §6: user, kind, size class, audience, deadline, streaming flag, and
+nothing else), a daemon claims it, and only then does the site seal the work to
+that specific device.
+
+The relay is a directory in that exchange, not a participant. It says "this
+device claimed your job, here is its public key" and carries what comes back.
+It cannot read a payload because it was never a recipient, and it cannot
+substitute one because the daemon verifies every envelope against the site
+identity it pinned at consent.
+
+That is not a policy this code follows. It is a shape it has: no type in this
+package has a field that could hold a private key, so making this relay able to
+read a payload means changing its types — a review someone has to justify
+rather than a line someone can slip in.
+
+## Why it ships open
+
+It is the conformance kit's reference relay, and the kit is public — so it
+starts where it ends rather than being written closed and ported. A relay that
+claims to be blind should be readable by the people trusting it, and a
+third-party daemon testing hub mode should test against real code rather than a
+mock of it.
+
+The production hub — multi-tenant routing, presence at scale, billing, ops — is
+built on these same interfaces and is not this.
+
+## `awaiting-payload`
+
+byollm_009 §7 described a state the direct plane cannot produce. There the site
+*is* the upstream: it seals when asked, so a job is never claimed-but-unsealed.
+Here they are different parties, and the gap between them is a state with its
+own clock — separate from the lease and from the job's TTL, because they answer
+different questions:
+
+| clock              | question                                       |
+| ------------------ | ---------------------------------------------- |
+| TTL                | is this work still worth doing?                |
+| lease              | how long does this device get to run it?       |
+| `awaiting-payload` | how long do we wait for a site that went away? |
+
+When it fires, the stub returns to the queue and nothing is lost.
+
+## Consent
+
+The relay routes nothing without a consent record, and it cannot create one —
+consent is a decision made elsewhere and projected in. In the skeleton that
+projection is a fixture file; later it is whatever the control plane serves.
+The shape is deliberately small, because it is a contract: anything added to it
+has to be something a control plane can actually know, and a decision rather
+than something the relay could observe for itself.
+
+## Both callers sign
+
+A daemon signs every request with its device key. **A site signs every request
+with its site key** — the same key the control plane registered, the same key
+daemons pin at pairing, verified against the `sites` half of the projection.
+Nothing here trusts a `siteId` in a body or a query string.
+
+That is newer than the rest of this package. The site plane took the caller's
+word for who it was until `0.1.0-alpha.10`, which on a relay reachable from the
+internet is an open enqueue endpoint into consenting users' machines and an
+open read of who is online. It was blind the whole time — nothing could open a
+payload — and blind is not the same as safe.
+
+If you are running this: the site plane is authenticated but this is still a
+single-tenant relay with in-memory state. One site, one replica.
+
+## Running it
+
+```ts
+import { Relay } from "@byollm/relay";
+
+const relay = new Relay({
+  siteId: "site_demo",
+  fixture: {
+    // The site registry: one home for a site's public identity, used both to
+    // tell daemons who to pin and to check the site's own signatures.
+    sites: [{ siteId: "site_demo", site: sitePublicKeys }],
+    consents: [{ owner: "alice", siteId: "site_demo" }],
+  },
+});
+
+// One fetch handler: the daemon plane, the site plane, and /debug.
+const response = await relay.handle(request);
+```
+
+`/debug` renders every routed job, its state, who claimed it, and how long an
+`awaiting-payload` timer has left. It shows no prompt or result text — not
+because it filters them out, but because the relay does not have them.
+
+**Do not serve `/debug` on the internet.** It shows no payloads and it does
+show who is online, which device holds what, and every lease in flight — the
+same metadata the site plane's signatures exist to protect, through a
+different door. Whoever serves this package decides that, which is why the
+route is still here: refuse it at your gateway and reach it through an
+authenticated channel instead.
+
+## Auditing a deployment
+
+`@byollm/conformance` ships a posture audit that holds nothing but a URL,
+which is what an attacker has:
+
+```bash
+npx byollm-audit-deployment https://your-relay.example
+```
+
+It exists because eight of byollm_009's findings came from a suite in which
+nothing was ever a stranger — the site had a reference to the relay object and
+called it. A harness that invokes the system under test directly cannot see
+anything about how the system is *reached*, and the ninth finding was in that
+gap. Safe to run against production: nothing writes, nothing floods.
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,416 @@
+import { PublicIdentity, JobStub, SealedEnvelope } from '@byollm/protocol';
+import { z } from 'zod';
+
+/**
+ * The relay's routing state — byollm_009 §7, reachable at last.
+ *
+ * §7 described a state machine the direct plane could not produce. There, the
+ * site and the upstream are the same party: it seals when it likes, and a job
+ * is never claimed-but-unsealed. Here they are different parties, and the gap
+ * between them is a state:
+ *
+ * ```
+ * queued ──claim──▶ awaiting-payload ──sealed──▶ ready ──fetch──▶ running
+ *    ▲                    │                                          │
+ *    └────────────────────┘                                          ▼
+ *      site never seals, or seals too late              ok | error | canceled
+ * ```
+ *
+ * The relay cannot seal, so it cannot shortcut this. A payload is encrypted
+ * to *the device that claimed it*, and nobody knows which device that is until
+ * the claim happens — which is precisely why claim-then-fetch makes a blind
+ * relay possible at all. The window is the price.
+ *
+ * ## What the relay holds, and what it cannot
+ *
+ * Stubs (metadata the site chose to publish), sealed envelopes it cannot open,
+ * and public keys. There is no field on any type in this file that could hold
+ * a private key or a plaintext, which is `RELAY_BLIND` expressed as a data
+ * model rather than as a policy.
+ */
+/** Where a routed job is. */
+type RoutedState = "queued" | "awaiting-payload" | "ready" | "running" | "done";
+/**
+ * How long a site has to seal after one of its jobs is claimed.
+ *
+ * **Distinct from the lease, and distinct from the job's TTL** — byollm_009
+ * §7.1. Three clocks, three different questions:
+ *
+ * - the **TTL** asks how long the work is worth doing at all;
+ * - the **lease** asks how long this device gets to run it;
+ * - this asks how long we wait for a site that has gone away.
+ *
+ * Collapsing any pair of them looks harmless until a site restarts during a
+ * deploy: with only a lease, the device sits politely holding a job whose
+ * payload will never arrive, and the lease's whole minute is spent waiting on
+ * a party that is not coming back. Short, because a site that is up answers in
+ * milliseconds and a site that is down will not answer sooner for waiting.
+ */
+declare const AWAITING_PAYLOAD_MS = 10000;
+/** A job the relay is routing. Metadata and ciphertext, nothing else. */
+interface RoutedJob {
+    readonly id: string;
+    /** Which site enqueued it — the party that will be asked to seal. */
+    readonly siteId: string;
+    /**
+     * Everything the relay knows about the work, which is everything the site
+     * chose to publish and not one field more (byollm_009 §6).
+     */
+    readonly stub: JobStub;
+    state: RoutedState;
+    /** Set from the claim; the site seals to these keys. */
+    claimedBy?: {
+        readonly runnerId: string;
+        readonly owner: string;
+        readonly device: PublicIdentity;
+        readonly leaseId: string;
+        readonly leaseExpiresAt: number;
+    };
+    /** When {@link AWAITING_PAYLOAD_MS} runs out for this claim. */
+    awaitingUntil?: number;
+    /** Sealed to the claiming device by the site. Opaque here. */
+    payload?: SealedEnvelope;
+    /** Sealed to the site by the device. Opaque here. */
+    result?: SealedEnvelope;
+    /**
+     * The result's clear-text discriminator — byollm_009 §6.1.
+     *
+     * The one outcome fact the relay is given, and the reason it is given:
+     * without it the relay cannot stop dispatching a finished job. A routing
+     * hint and never a fact — the *site* verifies it against the sealed
+     * outcome, because only the site can open the envelope. The relay acts on
+     * it and is entitled to be wrong; a lying daemon costs it a dispatch
+     * decision, not a security property.
+     */
+    disposition?: "ok" | "error" | "canceled";
+}
+/** A device the relay has seen recently. */
+interface Presence {
+    readonly runnerId: string;
+    readonly owner: string;
+    readonly device: PublicIdentity;
+    lastSeenAt: number;
+    /** Set on revocation so the next request is refused rather than routed. */
+    revoked: boolean;
+}
+/**
+ * In-memory routing state.
+ *
+ * Deliberately not durable. The skeleton proves the protocol, and the
+ * production hub replaces this with the closed multi-tenant router behind the
+ * same shape (cloud_004 §9). Anything a restart loses here is a job that
+ * returns to its site's queue — which is the behaviour a lapsed lease already
+ * has to produce, so nothing new needs to be true for this to be safe.
+ */
+declare class RelayState {
+    #private;
+    /**
+     * Take a stub for routing. The payload is not here and will not be.
+     *
+     * **Idempotent by job id, and that is a security property rather than a
+     * convenience.** Site-plane calls are authenticated by signature, and
+     * byollm_009 §4.2's argument for signing the request instead of a
+     * server-issued nonce rests entirely on every write being idempotent per the
+     * instance it names. This one was not: re-enqueueing a known id built a
+     * fresh `queued` job over the top of the old one, discarding a live claim,
+     * its lease and any payload the site had already sealed to a device. A
+     * replayed enqueue inside the two-minute freshness window was therefore a
+     * way to yank a job back from the machine running it — the `release` bug of
+     * §4.2, rediscovered on the other plane.
+     *
+     * So a known id returns what is already routing, unchanged. A site that
+     * restarts and republishes its queue is the normal case, and it must not
+     * disturb work in flight.
+     */
+    enqueue(input: {
+        id: string;
+        siteId: string;
+        stub: JobStub;
+    }): RoutedJob;
+    job(jobId: string): RoutedJob | undefined;
+    jobs(): RoutedJob[];
+    /** Jobs a site must seal for, right now. */
+    awaiting(siteId: string): RoutedJob[];
+    /** Sealed results waiting to go home. */
+    finished(siteId: string): RoutedJob[];
+    seen(presence: Omit<Presence, "revoked">): Presence;
+    presence(runnerId: string): Presence | undefined;
+    everyone(): Presence[];
+    /**
+     * Return a job to the queue, forgetting the claim.
+     *
+     * The stub survives; nothing is lost. That is `LEASE_RECLAIMABLE` and it is
+     * why the awaiting-payload timeout is cheap to fire: the worst case is that
+     * a device did nothing for ten seconds and another one gets a turn.
+     */
+    requeue(job: RoutedJob): void;
+    /**
+     * Fire whatever the clock says is due, and report it.
+     *
+     * Returns the jobs it requeued so a caller can log or surface them — a
+     * timeout that fires invisibly is indistinguishable from a job that was
+     * never claimed, and those want very different debugging.
+     */
+    sweep(now: number): RoutedJob[];
+}
+
+declare function debugPage(state: RelayState, now: number): string;
+
+/**
+ * What the relay is told about the world — cloud_004 §14.
+ *
+ * The relay decides nothing about who may talk to whom. It is handed a
+ * projection of the control plane and routes according to it. Today that
+ * projection is a file; later it is whatever the suite serves. Either way the
+ * relay's own state is derived and disposable: delete it and the fixture
+ * rebuilds it.
+ *
+ * ## This shape is a contract, not a test convenience
+ *
+ * cloud_004 §14 flags it and the flag is worth repeating here, where someone
+ * will be tempted to add a field: **this is the projection contract.** The
+ * first real control plane will be written to produce whatever this says, and
+ * a field added carelessly now is a field the suite must produce forever.
+ *
+ * So two rules for anything added later:
+ *
+ * 1. **It must be something a control plane can actually know.** The relay
+ *    cannot be given facts that only a daemon or only a site holds — that is
+ *    how a blind relay stops being blind, one convenient field at a time.
+ * 2. **It must be a decision, not a derivation.** Consent is a decision.
+ *    Presence is not: the relay learns that from heartbeats. Anything the
+ *    relay can observe does not belong in the projection.
+ *
+ * ## What is deliberately absent
+ *
+ * No private keys, of any party, ever. The relay holds public keys so it can
+ * *verify* signatures and *tell a site who to seal to*. It holds no key that
+ * can open anything, and {@link RelayFixture} has no field where one could be
+ * put — `RELAY_BLIND` as a type, not as a promise.
+ */
+/**
+ * A site the control plane registered and domain-verified — cloud_004 §5.
+ *
+ * **The one authority for a site's public identity.** It used to be inlined on
+ * every consent record, which meant a site's key had as many homes as it had
+ * users and nothing checked they agreed — the exact shape this project has now
+ * found in a version constant, a clock read, an envelope deadline, a reseal
+ * implementation, a package list and a docs page. Consents now reference a
+ * site by id and the key is looked up here.
+ *
+ * The relay needs it for two things it cannot do without:
+ *
+ * 1. **Telling a daemon who to pin** at pairing — the key that makes relayed
+ *    work unforgeable, since the relay holds no key that could produce it.
+ * 2. **Authenticating the site plane.** A site calls a relay the way a daemon
+ *    does, signing with this identity, and this is the key those signatures
+ *    are checked against.
+ */
+declare const SiteRecord: z.ZodObject<{
+    siteId: z.ZodString;
+    site: z.ZodObject<{
+        identity: z.ZodString;
+        encryption: z.ZodString;
+        encryptionSig: z.ZodString;
+    }, z.core.$strict>;
+}, z.core.$strict>;
+type SiteRecord = z.infer<typeof SiteRecord>;
+/**
+ * A user's decision to let one site use their compute — cloud_004 §3.
+ *
+ * `CONSENT_BEFORE_ROUTE`: with no record here, the relay refuses to route,
+ * and there is no discovery path that creates one. Consent is a click in the
+ * control plane; the relay only ever reads the result.
+ */
+declare const ConsentRecord: z.ZodObject<{
+    owner: z.ZodString;
+    siteId: z.ZodString;
+}, z.core.$strict>;
+type ConsentRecord = z.infer<typeof ConsentRecord>;
+/**
+ * A named group whose members may use a shared machine — cloud_004 §11.
+ *
+ * The roster lives here and **never reaches a site**. A site learns whether a
+ * consenting user has reachable compute; it never learns who else is on the
+ * roster. That is `ROSTERS_NEVER_LEAK` in cloud_004 §11.4, and the reason
+ * this type has no outbound representation anywhere in this package.
+ */
+declare const RosterRecord: z.ZodObject<{
+    id: z.ZodString;
+    owner: z.ZodString;
+    members: z.ZodArray<z.ZodString>;
+}, z.core.$strict>;
+type RosterRecord = z.infer<typeof RosterRecord>;
+/**
+ * A device its owner has approved — cloud_005 §7.1.
+ *
+ * The relay refuses a device that is not here, and that refusal is the point.
+ * byollm_009's seventh finding stopped a daemon from *naming* itself; this
+ * stops it from *keying* itself. A device that presents keys nobody approved
+ * is a device whose owner never saw a fingerprint, and pairing it would make
+ * the relay the authority on identity — which is exactly what it must not be.
+ *
+ * The three-party shape consent already has, applied to identity: the device
+ * asserts, a human confirms in the control plane, the relay checks.
+ */
+declare const DeviceRecord: z.ZodObject<{
+    owner: z.ZodString;
+    runnerId: z.ZodString;
+    device: z.ZodObject<{
+        identity: z.ZodString;
+        encryption: z.ZodString;
+        encryptionSig: z.ZodString;
+    }, z.core.$strict>;
+}, z.core.$strict>;
+type DeviceRecord = z.infer<typeof DeviceRecord>;
+/** A revoked route, named by its parts. */
+declare const RevocationRecord: z.ZodObject<{
+    owner: z.ZodString;
+    siteId: z.ZodString;
+}, z.core.$strict>;
+type RevocationRecord = z.infer<typeof RevocationRecord>;
+declare const RelayFixture: z.ZodObject<{
+    sites: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        siteId: z.ZodString;
+        site: z.ZodObject<{
+            identity: z.ZodString;
+            encryption: z.ZodString;
+            encryptionSig: z.ZodString;
+        }, z.core.$strict>;
+    }, z.core.$strict>>>;
+    consents: z.ZodArray<z.ZodObject<{
+        owner: z.ZodString;
+        siteId: z.ZodString;
+    }, z.core.$strict>>;
+    devices: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        owner: z.ZodString;
+        runnerId: z.ZodString;
+        device: z.ZodObject<{
+            identity: z.ZodString;
+            encryption: z.ZodString;
+            encryptionSig: z.ZodString;
+        }, z.core.$strict>;
+    }, z.core.$strict>>>;
+    rosters: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        owner: z.ZodString;
+        members: z.ZodArray<z.ZodString>;
+    }, z.core.$strict>>>;
+    revoked: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        owner: z.ZodString;
+        siteId: z.ZodString;
+    }, z.core.$strict>>>;
+}, z.core.$strict>;
+type RelayFixture = z.infer<typeof RelayFixture>;
+/** An empty projection: nothing consented, so nothing routes. */
+declare const EMPTY_FIXTURE: RelayFixture;
+/**
+ * The relay's read-only view of the projection.
+ *
+ * Deliberately a handful of questions rather than the raw fixture: every
+ * caller asking "may this route?" through one method is what makes
+ * `CONSENT_BEFORE_ROUTE` reviewable, and it leaves room for the projection to
+ * become a service without touching a single call site.
+ */
+declare class Projection {
+    #private;
+    constructor(fixture?: RelayFixture);
+    /** Replace the projection wholesale — the control plane pushed a new one. */
+    replace(fixture: RelayFixture): void;
+    /**
+     * The site this id names, if the control plane registered it.
+     *
+     * The only source of a site's public identity in this package. Everything
+     * that pins, verifies or seals to a site starts here.
+     */
+    siteFor(siteId: string): SiteRecord | null;
+    /**
+     * The device this runner id names, if a human approved it.
+     *
+     * Returns null for a device the control plane does not know, which is how
+     * the relay refuses to be the authority on identity.
+     */
+    deviceFor(runnerId: string): DeviceRecord | null;
+    /** The device approved for these exact keys, if any. */
+    deviceByFingerprint(identityPublic: string): DeviceRecord | null;
+    /** The consent binding this owner to this site, if it exists and stands. */
+    consentFor(owner: string, siteId: string): ConsentRecord | null;
+    /**
+     * May this device's owner run work belonging to `jobOwner`?
+     *
+     * The relay's half of `AUDIENCE_BOTH_SIDES`. It is only ever a *narrowing*:
+     * the daemon re-checks its own allowlist locally and may still refuse, and
+     * the site's audience already bounded who could be offered the job. A relay
+     * that answered `true` for everyone would not widen anything — which is
+     * exactly the property that lets it be blind.
+     */
+    mayRunFor(deviceOwner: string, jobOwner: string): boolean;
+}
+
+/**
+ * `@byollm/relay` — the reference relay (cloud_004 §14).
+ *
+ * A blind relay between byollm sites and daemons: it routes stubs, hands over
+ * sealed envelopes it cannot open, and knows who is online. It is the first
+ * consumer of byollm_009's session layer that is neither the site nor the
+ * device, which makes it the thing that proves the protocol's central claim.
+ *
+ * ## Why this ships open
+ *
+ * It is the conformance kit's reference relay, and the kit is public — so it
+ * starts where it ends rather than being written closed and ported. A relay
+ * that claims to be blind should be readable by the people trusting it, and a
+ * third-party daemon testing hub mode should test against real code rather
+ * than a mock of it. The production hub — multi-tenant routing, presence at
+ * scale, billing, ops — is built on these same interfaces and is not this.
+ *
+ * ## Blind by construction, not by policy
+ *
+ * {@link RelayOptions} has no field that can hold a private key, and no type
+ * in this package has one either. `RELAY_BLIND` is therefore not a rule the
+ * code follows; it is a shape the code has. The only way to make this relay
+ * able to read a payload is to change its types, which is a review someone
+ * would have to justify rather than a line someone could slip in.
+ */
+interface RelayOptions {
+    /**
+     * Which site this relay routes for.
+     *
+     * One, in the skeleton. Multi-tenant routing is the closed piece
+     * (cloud_004 §9), and it replaces this field rather than extending it.
+     */
+    readonly siteId: string;
+    /** Consent and rosters, projected from the control plane. */
+    readonly fixture?: RelayFixture;
+    /** How long a claim is good for. */
+    readonly leaseMs?: number;
+    /** Injectable clock, so tests move time instead of sleeping. */
+    readonly now?: () => number;
+    /** Where the daemon plane is mounted. */
+    readonly basePath?: string;
+}
+/** A running relay: one fetch handler, two planes, one debug page. */
+declare class Relay {
+    #private;
+    readonly state: RelayState;
+    readonly projection: Projection;
+    constructor(options: RelayOptions);
+    /** Replace the projection — a control-plane push, or a fixture edit. */
+    project(fixture: RelayFixture): void;
+    /**
+     * Fire due timers and report what moved.
+     *
+     * Exposed rather than run on an interval so a test can drive it, and so the
+     * production hub can decide its own scheduling. The relay never needs a
+     * timer to be *correct* — every read path sweeps first — but a job whose
+     * site vanished should return to the queue without waiting for someone to
+     * ask about it.
+     */
+    sweep(): {
+        requeued: string[];
+    };
+    /** The whole HTTP surface. */
+    handle(request: Request): Promise<Response>;
+}
+
+export { AWAITING_PAYLOAD_MS, ConsentRecord, DeviceRecord, EMPTY_FIXTURE, type Presence, Projection, Relay, RelayFixture, RelayFixture as RelayFixtureSchema, type RelayOptions, RelayState, RevocationRecord, RosterRecord, type RoutedJob, type RoutedState, SiteRecord, debugPage };