sealbridge 0.0.1 → 0.2.0

package/dist/packages/ledger/dist/index.d.ts

@@ -0,0 +1,84 @@
+import type { Json, Signature, AckReceipt, KeyPair, Signed } from '@acp/core';
+export interface AuditBody {
+    taskId: string;
+    seq: number;
+    prevEntryHash: string | null;
+    actorDid: string;
+    receiverDid: string;
+    eventType: string;
+    payload: Json;
+}
+export interface AuditEntry {
+    body: AuditBody;
+    entryHash: string;
+    actorSignature: Signature;
+    counterSignature: AckReceipt;
+}
+export interface Checkpoint {
+    type: 'AuditCheckpoint';
+    taskId: string;
+    count: number;
+    head: string | null;
+    actors: [string, string];
+}
+export interface AuditBundle {
+    entries: AuditEntry[];
+    checkpoint: {
+        actor: Signed<Checkpoint>;
+        receiver: Signed<Signed<Checkpoint>>;
+    };
+}
+export interface AuditStore {
+    read(): AuditEntry[];
+    append(entry: AuditEntry, checkpoint: AuditBundle['checkpoint']): void;
+    seal?(checkpoint: AuditBundle['checkpoint']): void;
+}
+export declare class MemoryStore implements AuditStore {
+    #private;
+    read(): AuditEntry[];
+    append(entry: AuditEntry): void;
+}
+export declare class JsonlStore implements AuditStore {
+    readonly path: string;
+    constructor(path: string);
+    private records;
+    read(): AuditEntry[];
+    append(entry: AuditEntry): void;
+    seal(checkpoint: AuditBundle['checkpoint']): void;
+}
+export declare function parseJsonl(text: string): AuditBundle;
+export declare class BilateralLedger {
+    readonly taskId: string;
+    readonly actors: [string, string];
+    readonly store: AuditStore;
+    constructor(taskId: string, actors: [string, string], store?: AuditStore);
+    private checkpoint;
+    append(eventType: string, payload: Json, actor: KeyPair, receiver: KeyPair): AuditEntry;
+    bundle(actor: KeyPair, receiver: KeyPair): AuditBundle;
+}
+/** External pin for the bilateral checkpoint. `head` is the checkpoint head. */
+export interface AuditTrustAnchor {
+    taskId?: string;
+    actors?: [string, string];
+    head?: string;
+    expectedFinalState?: string;
+    expectedLastEntryHash?: string;
+    expectedEntryCount?: number;
+}
+export interface AuditVerificationOptions extends AuditTrustAnchor {
+    trustAnchor?: AuditTrustAnchor;
+}
+export interface AuditVerificationResult {
+    valid: boolean;
+    status: 'VALID' | 'INVALID';
+    statusLabel: string;
+    trustAnchorVerified: boolean;
+    truncationChecked: boolean;
+    reason?: string;
+}
+/**
+ * Intact chain with no external anchor. A hash chain cannot tell a complete
+ * older log from the current one, so tail truncation is not checked.
+ */
+export declare const AUDIT_VALID_WITHOUT_TRUST_ANCHOR = "VALID (no trust anchor: truncation not checked)";
+export declare function verifyAudit(bundle: AuditBundle, expected?: AuditVerificationOptions): AuditVerificationResult;

package/dist/packages/ledger/dist/index.js

@@ -0,0 +1,269 @@
+// SPDX-License-Identifier: Apache-2.0
+import { appendFileSync, readFileSync } from 'node:fs';
+import { digest, signPayload, signAck, verifySigned, verifySignature, validateSchema, } from '../../core/dist/index.js';
+export class MemoryStore {
+    #entries = [];
+    read() {
+        return structuredClone(this.#entries);
+    }
+    append(entry) {
+        this.#entries.push(structuredClone(entry));
+    }
+}
+export class JsonlStore {
+    path;
+    constructor(path) {
+        this.path = path;
+    }
+    records() {
+        try {
+            return readFileSync(this.path, 'utf8')
+                .trim()
+                .split('\n')
+                .filter(Boolean)
+                .map((l) => JSON.parse(l));
+        }
+        catch (e) {
+            if (e.code === 'ENOENT')
+                return [];
+            throw e;
+        }
+    }
+    read() {
+        return this.records()
+            .filter((r) => r.entry)
+            .map((r) => r.entry);
+    }
+    append(entry) {
+        if (this.records().some((r) => r.checkpoint))
+            throw new Error('LEDGER_SEALED');
+        appendFileSync(this.path, JSON.stringify({ entry }) + '\n', { mode: 0o600 });
+    }
+    seal(checkpoint) {
+        const old = this.records().at(-1)?.checkpoint;
+        if (old) {
+            if (digest(old.actor.payload) !== digest(checkpoint.actor.payload))
+                throw new Error('LEDGER_SEALED');
+            return;
+        }
+        appendFileSync(this.path, JSON.stringify({ checkpoint }) + '\n', { mode: 0o600 });
+    }
+}
+export function parseJsonl(text) {
+    const records = text
+        .trim()
+        .split('\n')
+        .filter(Boolean)
+        .map((l) => JSON.parse(l));
+    const last = records.pop();
+    if (!last?.checkpoint || last.entry || records.some((r) => !r.entry || r.checkpoint))
+        throw new Error('MISSING_OR_MISPLACED_CHECKPOINT');
+    return { entries: records.map((r) => r.entry), checkpoint: last.checkpoint };
+}
+export class BilateralLedger {
+    taskId;
+    actors;
+    store;
+    constructor(taskId, actors, store = new MemoryStore()) {
+        this.taskId = taskId;
+        this.actors = actors;
+        this.store = store;
+        if (actors[0] === actors[1])
+            throw new Error('DISTINCT_ACTORS_REQUIRED');
+    }
+    checkpoint(entries, actor, receiver) {
+        const payload = {
+            type: 'AuditCheckpoint',
+            taskId: this.taskId,
+            count: entries.length,
+            head: entries.at(-1)?.entryHash ?? null,
+            actors: this.actors,
+        };
+        const signed = signPayload(payload, actor);
+        return { actor: signed, receiver: signPayload(signed, receiver) };
+    }
+    append(eventType, payload, actor, receiver) {
+        if (actor.did === receiver.did ||
+            !this.actors.includes(actor.did) ||
+            !this.actors.includes(receiver.did))
+            throw new Error('INVALID_LEDGER_PARTIES');
+        const entries = this.store.read();
+        if (!verifyAudit({ entries, checkpoint: this.checkpoint(entries, actor, receiver) }).valid)
+            throw new Error('CORRUPT_EXISTING_LEDGER');
+        const body = {
+            taskId: this.taskId,
+            seq: entries.length,
+            prevEntryHash: entries.at(-1)?.entryHash ?? null,
+            actorDid: actor.did,
+            receiverDid: receiver.did,
+            eventType,
+            payload,
+        };
+        const entryHash = digest(body), actorSignature = signPayload(body, actor).signature;
+        const counterSignature = signAck({
+            type: 'AckReceipt',
+            taskId: this.taskId,
+            entryHash,
+            actorDid: actor.did,
+            receiverDid: receiver.did,
+        }, receiver);
+        const entry = { body, entryHash, actorSignature, counterSignature };
+        validateSchema('audit-entry', entry);
+        this.store.append(entry, this.checkpoint([...entries, entry], actor, receiver));
+        return entry;
+    }
+    bundle(actor, receiver) {
+        const entries = this.store.read();
+        const checkpoint = this.checkpoint(entries, actor, receiver);
+        this.store.seal?.(checkpoint);
+        return { entries, checkpoint };
+    }
+}
+/**
+ * Intact chain with no external anchor. A hash chain cannot tell a complete
+ * older log from the current one, so tail truncation is not checked.
+ */
+export const AUDIT_VALID_WITHOUT_TRUST_ANCHOR = 'VALID (no trust anchor: truncation not checked)';
+function hasText(value) {
+    return typeof value === 'string' && value.length > 0;
+}
+function textField(primary, fallback) {
+    if (hasText(primary))
+        return primary;
+    if (hasText(fallback))
+        return fallback;
+    return undefined;
+}
+function anchorSupplied(options) {
+    if (!options)
+        return false;
+    return [options, options.trustAnchor].some((part) => {
+        if (!part)
+            return false;
+        return (part.taskId !== undefined ||
+            part.actors !== undefined ||
+            hasText(part.head) ||
+            hasText(part.expectedFinalState) ||
+            hasText(part.expectedLastEntryHash) ||
+            typeof part.expectedEntryCount === 'number');
+    });
+}
+function sameAnchorField(left, right) {
+    if (left === undefined || right === undefined)
+        return true;
+    return digest(left) === digest(right);
+}
+function resolveAnchor(options) {
+    const nested = options?.trustAnchor;
+    if (options &&
+        nested &&
+        (!sameAnchorField(options.taskId, nested.taskId) ||
+            !sameAnchorField(options.actors, nested.actors) ||
+            !sameAnchorField(options.head, nested.head) ||
+            !sameAnchorField(options.expectedFinalState, nested.expectedFinalState) ||
+            !sameAnchorField(options.expectedLastEntryHash, nested.expectedLastEntryHash) ||
+            !sameAnchorField(options.expectedEntryCount, nested.expectedEntryCount)))
+        throw new Error('trust anchor');
+    return {
+        taskId: options?.taskId ?? nested?.taskId,
+        actors: options?.actors ?? nested?.actors,
+        head: textField(options?.head, nested?.head),
+        expectedFinalState: textField(options?.expectedFinalState, nested?.expectedFinalState),
+        expectedLastEntryHash: textField(options?.expectedLastEntryHash, nested?.expectedLastEntryHash),
+        expectedEntryCount: options?.expectedEntryCount ?? nested?.expectedEntryCount,
+    };
+}
+function assertTrustAnchor(anchor, checkpoint, entries) {
+    if (anchor.taskId !== undefined && anchor.taskId !== checkpoint.taskId)
+        throw new Error('trust anchor');
+    if (anchor.actors !== undefined) {
+        if (!Array.isArray(anchor.actors) ||
+            anchor.actors.length !== 2 ||
+            digest(anchor.actors) !== digest(checkpoint.actors))
+            throw new Error('trust anchor');
+    }
+    const last = entries.at(-1)?.entryHash ?? null;
+    if (anchor.head !== undefined && anchor.head !== checkpoint.head)
+        throw new Error('trust anchor');
+    if (anchor.expectedLastEntryHash !== undefined && anchor.expectedLastEntryHash !== last)
+        throw new Error('trust anchor');
+    if (anchor.expectedEntryCount !== undefined) {
+        if (typeof anchor.expectedEntryCount !== 'number' ||
+            !Number.isSafeInteger(anchor.expectedEntryCount) ||
+            anchor.expectedEntryCount < 0 ||
+            anchor.expectedEntryCount !== checkpoint.count)
+            throw new Error('trust anchor');
+    }
+    if (anchor.expectedFinalState !== undefined &&
+        entries.at(-1)?.body.eventType !== anchor.expectedFinalState)
+        throw new Error('trust anchor');
+}
+function auditResult(supplied, error) {
+    if (error !== undefined)
+        return {
+            valid: false,
+            status: 'INVALID',
+            statusLabel: 'INVALID',
+            trustAnchorVerified: false,
+            truncationChecked: supplied,
+            reason: String(error),
+        };
+    if (!supplied)
+        return {
+            valid: true,
+            status: 'VALID',
+            statusLabel: AUDIT_VALID_WITHOUT_TRUST_ANCHOR,
+            trustAnchorVerified: false,
+            truncationChecked: false,
+        };
+    return {
+        valid: true,
+        status: 'VALID',
+        statusLabel: 'VALID',
+        trustAnchorVerified: true,
+        truncationChecked: true,
+    };
+}
+export function verifyAudit(bundle, expected) {
+    const supplied = anchorSupplied(expected);
+    try {
+        const { entries, checkpoint } = bundle, c = checkpoint.actor.payload;
+        const selfDelegated = Array.isArray(c?.actors) && c.actors.length === 2 && c.actors[0] === c.actors[1];
+        if (c.type !== 'AuditCheckpoint' ||
+            c.actors.length !== 2 ||
+            !c.actors.includes(checkpoint.actor.signature.signerDid) ||
+            !c.actors.includes(checkpoint.receiver.signature.signerDid) ||
+            (!selfDelegated &&
+                checkpoint.actor.signature.signerDid === checkpoint.receiver.signature.signerDid) ||
+            !verifySigned(checkpoint.actor) ||
+            !verifySigned(checkpoint.receiver) ||
+            digest(checkpoint.receiver.payload) !== digest(checkpoint.actor) ||
+            c.count !== entries.length ||
+            c.head !== (entries.at(-1)?.entryHash ?? null))
+            throw new Error('checkpoint');
+        assertTrustAnchor(resolveAnchor(expected), c, entries);
+        for (let i = 0; i < entries.length; i++) {
+            const e = entries[i], b = e.body, a = e.counterSignature;
+            validateSchema('audit-entry', e);
+            if (b.taskId !== c.taskId ||
+                b.seq !== i ||
+                b.prevEntryHash !== (entries[i - 1]?.entryHash ?? null) ||
+                e.entryHash !== digest(b) ||
+                !c.actors.includes(b.actorDid) ||
+                !c.actors.includes(b.receiverDid) ||
+                (!selfDelegated && b.actorDid === b.receiverDid) ||
+                !verifySignature(b, e.actorSignature, b.actorDid) ||
+                !verifySigned(a, b.receiverDid) ||
+                a.payload.entryHash !== e.entryHash ||
+                a.payload.taskId !== b.taskId ||
+                a.payload.actorDid !== b.actorDid ||
+                a.payload.receiverDid !== b.receiverDid)
+                throw new Error('entry ' + i);
+        }
+        return auditResult(supplied);
+    }
+    catch (e) {
+        return auditResult(supplied, e);
+    }
+}
+//# sourceMappingURL=index.js.map

package/dist/packages/ledger/dist/index.js.map

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

package/dist/packages/relay/dist/fetch.d.ts

@@ -0,0 +1,250 @@
+import type { SignedEnvelope, SignedAgentCard, RelayAuthAction, KeyPair } from '@acp/core/edge';
+import type { RelayWakeOptions, RelayWakeAttempt, RelayOperation, SignedRelayDeliveryStatus } from './notifications.js';
+export * from './notifications.js';
+export declare function verifyRelayEnvelope(e: SignedEnvelope, recipient?: string): boolean;
+/** Single signed envelope JSON body. Larger bodies are rejected before they are queued. */
+export declare const DEFAULT_MAX_ENVELOPE_BYTES: number;
+/** Unread envelopes kept for one recipient. */
+export declare const DEFAULT_MAX_QUEUE_SIZE = 256;
+/** Sum of queued envelope JSON sizes for one recipient. */
+export declare const DEFAULT_MAX_QUEUE_BYTES_PER_RECIPIENT: number;
+export declare const DEFAULT_ENVELOPE_TTL_MS: number;
+export declare const DEFAULT_SEEN_TTL_MS: number;
+export declare const DEFAULT_AUTH_SEEN_TTL_MS: number;
+export declare const DEFAULT_AGENT_CARD_TTL_MS: number;
+/** Caps the durable replay ring scanned when an inbox object wakes. */
+export declare const DEFAULT_MAX_SEEN_ENTRIES = 4096;
+export declare const DEFAULT_MAX_QUEUES = 10000;
+export declare const DEFAULT_MAX_AGENTS = 10000;
+export interface RelaySnapshot {
+    operations?: [string, RelayOperation][];
+    queues: [string, SignedEnvelope[]][];
+    seen: string[];
+    authSeen?: string[];
+    agents: SignedAgentCard[];
+    envelopeExpiry?: [string, number][];
+    leaseExpiry?: [string, number][];
+    seenExpiry?: [string, number][];
+    authExpiry?: [string, number][];
+    agentExpiry?: [string, number][];
+}
+export interface InMemoryRelayOptions {
+    notificationKey?: KeyPair;
+    wake?: RelayWakeOptions;
+    /** Bounded expiry notices and wake deduplication retention; default one hour. */
+    notificationTtlMs?: number;
+    requireAuth?: boolean;
+    /**
+     * Direct and network checks accept a `RelayAuth` token that omits `origin`.
+     * A token that includes a different origin is still rejected.
+     */
+    allowUnboundRelayAuth?: boolean;
+    maxSeenEntries?: number;
+    maxAuthSeenEntries?: number;
+    maxQueues?: number;
+    maxQueueSize?: number;
+    maxEnvelopeBytes?: number;
+    maxQueueBytesPerRecipient?: number;
+    maxEnvelopesPerSender?: number;
+    maxAgents?: number;
+    envelopeTtlMs?: number;
+    seenTtlMs?: number;
+    authSeenTtlMs?: number;
+    agentCardTtlMs?: number;
+    now?: () => number;
+    tamper?: (e: SignedEnvelope) => SignedEnvelope;
+}
+export type RelayInboxRole = 'worker' | 'requester';
+export interface RelayReceiveFilter {
+    taskId?: string | readonly string[];
+    role?: RelayInboxRole;
+    peek?: boolean;
+    lease?: boolean;
+}
+interface TaskRoleState {
+    crossRole: Map<string, RelayInboxRole>;
+    lastPrimaryRole?: RelayInboxRole;
+    pendingAckRoles: RelayInboxRole[];
+    workerSeq: number;
+    requesterSeq: number;
+}
+interface NormalizedReceiveFilter {
+    taskIds?: Set<string>;
+    role?: RelayInboxRole;
+    peek: boolean;
+    lease?: boolean;
+}
+export declare function classifyEnvelopeRole(envelope: SignedEnvelope, state?: TaskRoleState): RelayInboxRole;
+export declare function normalizeReceiveFilter(filter?: RelayReceiveFilter): NormalizedReceiveFilter;
+export declare function parseReceiveFilterFromUrl(url: URL): RelayReceiveFilter | undefined;
+export declare function inboxRecipientFromRequest(path: string, url: URL): string | undefined;
+export declare function relayLimitsFromEnv(env?: Record<string, unknown>): InMemoryRelayOptions;
+export declare function canonicalRelayPath(pathname: string): string;
+/**
+ * Registry identity for one owner's registration of one agent.
+ * did:key values do not contain "/", so the pair round-trips unambiguously.
+ */
+export declare function agentRegistryKey(ownerDid: string, agentDid: string): string;
+/**
+ * Use the same verified, deterministic DID selection as requesters.
+ */
+export declare function selectAgentCard(cards: Iterable<SignedAgentCard>, agentDid: string, now?: number): SignedAgentCard | undefined;
+export declare class InMemoryRelay {
+    private operations;
+    private notificationKey;
+    private readonly wake?;
+    readonly notificationTtlMs: number;
+    private flushing?;
+    get notificationDid(): string;
+    /** Durable hosts install the persisted relay identity before restoring queues. */
+    setNotificationKey(key: KeyPair): void;
+    private queues;
+    private taskStates;
+    private seen;
+    private authSeen;
+    private agentExpiry;
+    private version;
+    get mutationVersion(): number;
+    private listeners;
+    /** Keyed by agentRegistryKey(ownerDid, agentDid). One owner cannot block another. */
+    readonly agents: Map<string, SignedAgentCard>;
+    readonly tamper?: (e: SignedEnvelope) => SignedEnvelope;
+    readonly requireAuth: boolean;
+    readonly allowUnboundRelayAuth: boolean;
+    readonly maxSeenEntries: number;
+    readonly maxAuthSeenEntries: number;
+    readonly maxQueues: number;
+    readonly maxQueueSize: number;
+    readonly maxEnvelopeBytes: number;
+    readonly maxQueueBytesPerRecipient: number;
+    readonly maxEnvelopesPerSender: number;
+    readonly maxAgents: number;
+    readonly envelopeTtlMs: number;
+    readonly seenTtlMs: number;
+    readonly authSeenTtlMs: number;
+    readonly agentCardTtlMs: number;
+    private readonly now;
+    constructor(options?: InMemoryRelayOptions | ((e: SignedEnvelope) => SignedEnvelope));
+    private remember;
+    authenticate(recipientDid: string, token?: string, action?: RelayAuthAction, check?: RelayAuthContext): boolean;
+    private stateForTask;
+    /** Authenticate once for a long poll or persistent stream, then read only this inbox. */
+    openInbox(recipientDid: string, token?: string, action?: RelayAuthAction, check?: RelayAuthContext, filter?: RelayReceiveFilter): () => SignedEnvelope | undefined;
+    private ensureQueue;
+    private putOperation;
+    registerWake(recipientDid: string, channel: string | null, token?: string, check?: RelayAuthContext): void;
+    private queueWake;
+    /** Claim inside a durable mutation turn and persist before invoking the channel. */
+    claimWakeNotification(): RelayWakeAttempt | undefined;
+    /** Run outside the durable mutation turn so notification latency cannot stall inbox delivery. */
+    deliverWakeNotification(attempt: RelayWakeAttempt): Promise<boolean>;
+    completeWakeNotification(attempt: RelayWakeAttempt, delivered: boolean): void;
+    /** In-memory hosts call periodically; durable hosts commit claims and completion separately. */
+    flushWakeNotifications(): Promise<void>;
+    getDeliveryStatus(recipientDid: string, envelopeId: string, senderDid: string, relay: string, token?: string, check?: RelayAuthContext): SignedRelayDeliveryStatus;
+    /** Drop queued envelopes, replay ids, and agent cards whose TTL has elapsed. */
+    evictExpired(): void;
+    private queuedBytes;
+    private senderCount;
+    send(envelope: SignedEnvelope): void;
+    receive(recipientDid: string, authToken?: string | number, _signal?: AbortSignal, checkOrFilter?: RelayAuthContext | RelayReceiveFilter, maybeFilter?: RelayReceiveFilter): SignedEnvelope | undefined;
+    peek(recipientDid: string, authTokenOrFilter?: string | Omit<RelayReceiveFilter, 'peek'>, check?: RelayAuthContext, filter?: Omit<RelayReceiveFilter, 'peek'>): SignedEnvelope | undefined;
+    pollInbox(recipientDid: string, authTokenOrFilter?: string | (RelayReceiveFilter & {
+        waitMs?: number;
+        signal?: AbortSignal;
+    }), filter?: RelayReceiveFilter, check?: RelayAuthContext): SignedEnvelope | undefined;
+    private dequeue;
+    /** Recipient-authenticated removal of one queued envelope. False when it is not queued. */
+    acknowledge(recipientDid: string, envelopeId: string, token?: string, check?: RelayAuthContext): boolean;
+    /** Seconds until the soonest queued item expires, for Retry-After. */
+    retryAfterSeconds(): number;
+    nextExpiry(): number | undefined;
+    withRecipient(key: KeyPair): {
+        send: (e: SignedEnvelope) => void;
+        deliveryStatus: (e: SignedEnvelope) => SignedRelayDeliveryStatus;
+        receive: (did: string, _waitMs?: number, signal?: AbortSignal, filter?: RelayReceiveFilter) => SignedEnvelope | undefined;
+        peek: (did: string, filter?: Omit<RelayReceiveFilter, "peek">) => SignedEnvelope | undefined;
+        pollInbox: (did: string, filter?: RelayReceiveFilter & {
+            waitMs?: number;
+            signal?: AbortSignal;
+        }) => SignedEnvelope | undefined;
+        register: (card: SignedAgentCard) => void;
+        discover: () => SignedAgentCard[];
+    };
+    subscribe(did: string, fn: () => void): () => void;
+    private hasMatching;
+    wait(did: string, ms: number, signal?: AbortSignal, filter?: RelayReceiveFilter): Promise<void>;
+    snapshot(): RelaySnapshot;
+    restore(snapshot: RelaySnapshot): void;
+    /** Authenticate even expired cards before allowing restore to discard them. */
+    private assertValidAgentSnapshot;
+    discover(): SignedAgentCard[];
+    register(card: SignedAgentCard): void;
+}
+export interface RelayAuthContext {
+    expectedOrigin?: string;
+    requireOrigin?: boolean;
+}
+export interface RelayRequestAuthOptions {
+    allowQueryAuth?: boolean;
+    requireOrigin?: boolean;
+    allowUnboundRelayAuth?: boolean;
+}
+export interface RelayFetchOptions extends RelayRequestAuthOptions {
+    relay?: InMemoryRelay;
+    agentCard?: SignedAgentCard;
+    deferNotifications?: boolean;
+}
+/** Defensive headers for any relay URL opened directly in a browser. */
+export declare function relayHttpHeaders(kind?: 'json' | 'empty' | 'sse'): Record<string, string>;
+/**
+ * Protocol codes the relay may place in an HTTP or WebSocket error body.
+ * A thrown message is returned only when it matches one of these strings exactly.
+ * Names that the live relay does not throw today stay listed so a later
+ * constant code is not replaced by RELAY_INTERNAL_ERROR.
+ */
+export declare const KNOWN_RELAY_ERROR_CODES: readonly ["INVALID_ENVELOPE", "INVALID_SIGNED_ENVELOPE", "ENVELOPE_EXPIRED", "REPLAYED_ENVELOPE", "DUPLICATE_ENVELOPE_ID", "ENVELOPE_TOO_LARGE", "RELAY_CAPACITY", "RELAY_QUEUE_FULL", "QUEUE_BYTES_EXCEEDED", "QUEUE_LIMIT_EXCEEDED", "RELAY_BYTE_BUDGET_EXCEEDED", "SENDER_QUOTA_EXCEEDED", "INVALID_RECIPIENT_DID", "MISSING_RECIPIENT_DID", "INVALID_DID", "RELAY_TAMPERING_DETECTED", "INVALID_AGENT_CARD", "INVALID_AGENT_SNAPSHOT", "AMBIGUOUS_AGENT_CARD_OWNER", "AGENT_CARD_EXPIRED", "AGENT_CARD_EXPIRY_TOO_LONG", "AGENT_CARD_DELEGATION_REQUIRED", "AGENT_DELEGATION_REQUIRED", "AGENT_CARD_DELEGATION_INVALID", "AGENT_CARD_TOO_LARGE", "AGENT_REGISTRY_FULL", "AGENT_CARD_TTL_INVALID", "AGENT_OWNER_OR_VERSION_MISMATCH", "NO_AGENT_REGISTERED", "RELAY_UNAUTHORIZED", "RELAY_AUTH_REQUIRED", "RELAY_AUTH_INVALID", "RELAY_AUTH_SIGNATURE_INVALID", "RELAY_AUTH_RECIPIENT_MISMATCH", "RELAY_AUTH_ACTION_MISMATCH", "RELAY_AUTH_EXPIRED", "RELAY_AUTH_FUTURE_ISSUED_AT", "RELAY_AUTH_REPLAYED", "RELAY_AUTH_NONCE_INVALID", "RELAY_AUTH_ORIGIN_REQUIRED", "RELAY_AUTH_ORIGIN_MISMATCH", "RELAY_QUERY_AUTH_DISABLED", "INVALID_RELAY_ORIGIN", "RATE_LIMITED", "RATE_LIMITER_UNAVAILABLE", "PAYLOAD_TOO_LARGE", "BODY_TOO_LARGE", "MISSING_BODY", "INVALID_JSON", "INVALID_UNICODE", "INVALID_LIMIT", "INVALID_RELAY_LIMIT", "INVALID_TIMEOUT", "INVALID_WAIT", "MISSING_ENVELOPE_ID", "UNSUPPORTED_METHOD", "NOT_FOUND", "WEBSOCKET_UPGRADE_REQUIRED", "INVALID_REQUEST", "INVALID_RELAY_SNAPSHOT", "RELAY_INTERNAL_ERROR"];
+/**
+ * Public error code for an untrusted caller.
+ * Parser and URL failures become INVALID_REQUEST. Any other message is returned
+ * only when it is an allowlisted code; otherwise the result is the fallback
+ * when that fallback is itself allowlisted, or RELAY_INTERNAL_ERROR.
+ */
+export declare function sanitizeRelayErrorCode(error: unknown, fallback?: string): string;
+export interface MappedRelayError {
+    status: number;
+    error: string;
+}
+/** Status and public code for one relay failure. Internal detail never leaves this function. */
+export declare function mapRelayError(error: unknown): MappedRelayError;
+/** Auth failures that must stay 401s with a stable error code. */
+export declare function relayAuthFailure(error: unknown): string | undefined;
+export declare function relayErrorResponse(error: unknown, relay?: InMemoryRelay): Response;
+/**
+ * Bearer credential for a relay request.
+ * `?auth=` is ignored unless `allowQueryAuth` is set, so tokens do not land in
+ * access logs, proxy logs, or Referer headers by default.
+ */
+export declare function extractRelayAuthToken(request: Request, options?: {
+    allowQueryAuth?: boolean;
+}, url?: URL): string | undefined;
+export declare function relayRequestToken(request: Request, url?: URL, options?: {
+    allowQueryAuth?: boolean;
+}): string | undefined;
+export declare function relayAuthContext(request: Request, relay: InMemoryRelay, options?: RelayRequestAuthOptions): RelayAuthContext;
+export type DurableLongPoll = {
+    mode: 'response';
+    response: Response;
+} | {
+    mode: 'wait';
+    recipient: string;
+    waitMs: number;
+    filter?: RelayReceiveFilter;
+    receive: () => SignedEnvelope | undefined;
+};
+/**
+ * Authenticate a long-poll and pop envelopes that are already queued.
+ * The caller waits outside the durable-object lock when the inbox is empty.
+ */
+export declare function beginDurableLongPoll(relay: InMemoryRelay, request: Request, auth?: RelayRequestAuthOptions): DurableLongPoll;
+export declare function createRelayFetchHandler(options?: RelayFetchOptions): (request: Request) => Promise<Response>;