@runeditrun/rer 0.0.0-stage → 0.1.0

package/modules/integrations/core/repository.ts

@@ -0,0 +1,74 @@
+import type { SqlDatabase, SqlStatement } from './database.ts';
+import type { Attempt, Delivery, Envelope, Outcome } from './types.ts';
+import { assertLabel, randomId } from './crypto.ts';
+
+export class IntegrationsRepository {
+  readonly namespace: string;
+  readonly sql: SqlDatabase;
+  constructor(sql: SqlDatabase, namespace: string) { assertLabel(namespace, 'namespace'); this.sql = sql; this.namespace = namespace; }
+  async query(sql: string, params: (string | number | null)[] = []) {
+    return (await this.sql.batch([{ sql, params: [this.namespace, ...params] }]))[0]!;
+  }
+  async insert(delivery: Delivery) {
+    await this.query(`INSERT INTO integration_deliveries(namespace,id,fingerprint,destination_hash,envelope,state,created_at,next_at,max_attempts,retry_delays)
+      VALUES(?,?,?,?,?,'queued',?,?,?,?) ON CONFLICT(namespace,id) DO NOTHING`,
+    [delivery.id, delivery.fingerprint, delivery.destinationHash, JSON.stringify(pickEnvelope(delivery)), delivery.createdAt, delivery.nextAt, delivery.maxAttempts, JSON.stringify(delivery.retryDelaysMs)]);
+    const current = (await this.get(delivery.id))!;
+    if (current.fingerprint !== delivery.fingerprint) throw new Error('Delivery identity conflict');
+    return current;
+  }
+  async get(id: string): Promise<Delivery | null> {
+    const row = (await this.query('SELECT * FROM integration_deliveries WHERE namespace=? AND id=?', [id]))[0];
+    return row ? { ...JSON.parse(String(row.envelope)), fingerprint: row.fingerprint, destinationHash: row.destination_hash, state: row.state,
+      attempts: row.attempts, createdAt: row.created_at, nextAt: row.next_at, claim: row.claim, claimUntil: row.claim_until,
+      maxAttempts: row.max_attempts, retryDelaysMs: JSON.parse(String(row.retry_delays)) } as Delivery : null;
+  }
+  async due(now: number, limit = 100) {
+    if (!Number.isSafeInteger(limit) || limit < 1 || limit > 1000) throw new Error('Invalid delivery batch limit');
+    return (await this.query("SELECT id FROM integration_deliveries WHERE namespace=? AND state='queued' AND next_at<=? AND attempts<max_attempts ORDER BY next_at,id LIMIT ?", [now, limit])).map(row => String(row.id));
+  }
+  async claim(id: string, now: number, leaseMs: number) {
+    const claim = randomId();
+    const statements: SqlStatement[] = [
+      { sql: `UPDATE integration_deliveries SET state='sending', attempts=attempts+1,claim=?,claim_until=? WHERE namespace=? AND id=? AND state='queued' AND next_at<=? AND attempts<max_attempts RETURNING id`, params: [claim, now + leaseMs, this.namespace, id, now] },
+      { sql: `INSERT INTO integration_attempts(namespace,id,delivery_id,number,started_at) SELECT namespace,claim,id,attempts,? FROM integration_deliveries WHERE namespace=? AND id=? AND claim=?`, params: [now, this.namespace, id, claim] },
+    ];
+    const result = await this.sql.batch(statements);
+    return result[0]!.length ? claim : null;
+  }
+  async finish(id: string, claim: string, outcome: Outcome, now: number, nextAt: number | null) {
+    const state = outcome.kind === 'retryable' ? (nextAt === null ? 'rejected' : 'queued') : outcome.kind;
+    const result = await this.sql.batch([
+      { sql: `UPDATE integration_attempts SET finished_at=?,outcome=? WHERE namespace=? AND id=? AND finished_at IS NULL AND EXISTS(SELECT 1 FROM integration_deliveries d WHERE d.namespace=? AND d.id=? AND d.state='sending' AND d.claim=? AND d.claim_until>?)`, params: [now, JSON.stringify(outcome), this.namespace, claim, this.namespace, id, claim, now] },
+      { sql: `UPDATE integration_deliveries SET state=?,claim=NULL,claim_until=NULL,next_at=? WHERE namespace=? AND id=? AND state='sending' AND claim=? AND claim_until>? RETURNING id`, params: [state, nextAt ?? now, this.namespace, id, claim, now] },
+    ]);
+    return result[1]!.length > 0;
+  }
+  async recoverExpired(now: number) {
+    const outcome = JSON.stringify({ kind: 'uncertain', code: 'claim_expired' });
+    const result = await this.sql.batch([
+      { sql: `UPDATE integration_attempts SET finished_at=?,outcome=? WHERE namespace=? AND finished_at IS NULL AND id IN (SELECT claim FROM integration_deliveries WHERE namespace=? AND state='sending' AND claim_until<=?)`, params: [now, outcome, this.namespace, this.namespace, now] },
+      { sql: `UPDATE integration_deliveries SET state='uncertain',claim=NULL,claim_until=NULL WHERE namespace=? AND state='sending' AND claim_until<=? RETURNING id`, params: [this.namespace, now] },
+    ]);
+    return result[1]!.map(row => String(row.id));
+  }
+  async log(id: string): Promise<Attempt[]> {
+    return (await this.query('SELECT * FROM integration_attempts WHERE namespace=? AND delivery_id=? ORDER BY number', [id])).map(r => ({ id: String(r.id), deliveryId: String(r.delivery_id), number: Number(r.number), startedAt: Number(r.started_at), finishedAt: r.finished_at === null ? null : Number(r.finished_at), outcome: r.outcome ? JSON.parse(String(r.outcome)) : null }));
+  }
+  async resolve(id: string, outcome: Outcome, now: number) {
+    const rows = await this.sql.batch([
+      { sql: `INSERT INTO integration_resolutions(namespace,id,delivery_id,at,outcome) SELECT namespace,?,id,?,? FROM integration_deliveries WHERE namespace=? AND id=? AND state='uncertain'`, params: [randomId(), now, JSON.stringify(outcome), this.namespace, id] },
+      { sql: `UPDATE integration_deliveries SET state=? WHERE namespace=? AND id=? AND state='uncertain' RETURNING id`, params: [outcome.kind, this.namespace, id] },
+    ]);
+    if (!rows[1]!.length) throw new Error('Delivery is not uncertain');
+  }
+  async resolutions(id: string) { return this.query('SELECT at,outcome FROM integration_resolutions WHERE namespace=? AND delivery_id=? ORDER BY at', [id]); }
+  async acceptReplay(input: { envelope: Envelope; fingerprint: string; receivedAt: number }) {
+    if (input.envelope.tenant !== this.namespace) throw new Error('Receiver namespace mismatch');
+    const rows = await this.query('INSERT INTO integration_replays(namespace,id,fingerprint,envelope,received_at) VALUES(?,?,?,?,?) ON CONFLICT(namespace,id) DO NOTHING RETURNING id', [input.envelope.id, input.fingerprint, JSON.stringify(input.envelope), input.receivedAt]);
+    const existing = (await this.query('SELECT fingerprint FROM integration_replays WHERE namespace=? AND id=?', [input.envelope.id]))[0]!;
+    if (existing.fingerprint !== input.fingerprint) throw new Error('Replay identity conflict');
+    return rows.length > 0;
+  }
+}
+export function pickEnvelope(e: Envelope): Envelope { return { id: e.id, tenant: e.tenant, destinationId: e.destinationId, event: e.event, protocol: e.protocol, body: e.body }; }

package/modules/integrations/core/schema.sql

@@ -0,0 +1,36 @@
+CREATE TABLE IF NOT EXISTS integration_deliveries (
+ namespace TEXT NOT NULL, id TEXT NOT NULL, fingerprint TEXT NOT NULL, destination_hash TEXT NOT NULL,
+ envelope TEXT NOT NULL, state TEXT NOT NULL CHECK(state IN ('queued','sending','accepted','rejected','uncertain')),
+ attempts INTEGER NOT NULL DEFAULT 0, created_at INTEGER NOT NULL, next_at INTEGER NOT NULL,
+ claim TEXT, claim_until INTEGER, max_attempts INTEGER NOT NULL, retry_delays TEXT NOT NULL,
+ PRIMARY KEY(namespace,id)
+);
+CREATE INDEX IF NOT EXISTS integration_deliveries_due ON integration_deliveries(namespace,state,next_at);
+CREATE TABLE IF NOT EXISTS integration_attempts (
+ namespace TEXT NOT NULL, id TEXT NOT NULL, delivery_id TEXT NOT NULL, number INTEGER NOT NULL,
+ started_at INTEGER NOT NULL, finished_at INTEGER, outcome TEXT,
+ PRIMARY KEY(namespace,id), UNIQUE(namespace,delivery_id,number)
+);
+CREATE TABLE IF NOT EXISTS integration_resolutions (
+ namespace TEXT NOT NULL, id TEXT NOT NULL, delivery_id TEXT NOT NULL, at INTEGER NOT NULL, outcome TEXT NOT NULL,
+ PRIMARY KEY(namespace,id)
+);
+CREATE TABLE IF NOT EXISTS integration_replays (
+ namespace TEXT NOT NULL, id TEXT NOT NULL, fingerprint TEXT NOT NULL, envelope TEXT NOT NULL, received_at INTEGER NOT NULL,
+ PRIMARY KEY(namespace,id)
+);
+CREATE TABLE IF NOT EXISTS integration_tokens (
+ namespace TEXT NOT NULL, id TEXT NOT NULL, token_hash TEXT NOT NULL, name TEXT NOT NULL, scopes TEXT NOT NULL,
+ created_at INTEGER NOT NULL, expires_at INTEGER, revoked_at INTEGER,
+ PRIMARY KEY(namespace,id), UNIQUE(namespace,token_hash)
+);
+CREATE TABLE IF NOT EXISTS integration_token_usage (
+ namespace TEXT NOT NULL, id TEXT NOT NULL, token_id TEXT, at INTEGER NOT NULL, required_scopes TEXT NOT NULL, allowed INTEGER NOT NULL,
+ request_id TEXT, resource TEXT,
+ PRIMARY KEY(namespace,id)
+);
+CREATE TABLE IF NOT EXISTS integration_token_events (
+ namespace TEXT NOT NULL, id TEXT NOT NULL, token_id TEXT NOT NULL, at INTEGER NOT NULL,
+ action TEXT NOT NULL, feature TEXT NOT NULL,
+ PRIMARY KEY(namespace,id)
+);

package/modules/integrations/core/sqlite.ts

@@ -0,0 +1,20 @@
+import { DatabaseSync } from 'node:sqlite';
+import type { SqlDatabase, SqlStatement } from './database.ts';
+/** Node 22.13+ SQLite. Durable files should be on a local filesystem with reliable locking. */
+export class SqliteDatabase implements SqlDatabase {
+  private db: DatabaseSync;
+  constructor(path: string) {
+    this.db = new DatabaseSync(path);
+    this.db.exec('PRAGMA busy_timeout=5000; PRAGMA journal_mode=WAL; PRAGMA synchronous=FULL;');
+  }
+  migrate(sql: string) { this.db.exec(sql); }
+  close() { this.db.close(); }
+  async batch(statements: SqlStatement[]): Promise<Record<string, unknown>[][]> {
+    this.db.exec('BEGIN IMMEDIATE');
+    try {
+      const result = statements.map(s => this.db.prepare(s.sql).all(...(s.params ?? [])) as Record<string, unknown>[]);
+      this.db.exec('COMMIT');
+      return result;
+    } catch (error) { this.db.exec('ROLLBACK'); throw error; }
+  }
+}

package/modules/integrations/core/timestamped-body-signature.ts

@@ -0,0 +1,38 @@
+import { hmacBytes } from './crypto.ts';
+import type { Envelope } from './types.ts';
+
+export interface TimestampedBodySignature {
+  timestampHeader: string;
+  signatureHeader: string;
+  /** Omit to reuse the Base webhook signing key resolved for this preparation. */
+  signingKey?: (envelope: Envelope) => Promise<Uint8Array>;
+}
+
+const reservedHeaders = new Set([
+  'content-type', 'webhook-id', 'webhook-tenant', 'webhook-destination',
+  'webhook-event', 'webhook-timestamp', 'webhook-signature',
+  'host', 'connection', 'content-length', 'transfer-encoding', 'proxy-authorization',
+  'authorization', 'keep-alive', 'proxy-connection', 'te', 'trailer', 'upgrade',
+]);
+const headerToken = /^[!#$%&'*+.^_`|~0-9A-Za-z-]+$/;
+
+export function timestampedBodySigner(options: TimestampedBodySignature) {
+  // Snapshot trusted configuration so later mutation cannot bypass validation.
+  const { timestampHeader, signatureHeader, signingKey } = options;
+  const names = [timestampHeader, signatureHeader];
+  if (names.some(name => typeof name !== 'string' || !headerToken.test(name)))
+    throw new Error('Invalid timestamped-body signature header name');
+  const normalized = names.map(name => name.toLowerCase());
+  if (new Set(normalized).size !== 2 || normalized.some(name => reservedHeaders.has(name)))
+    throw new Error('Timestamped-body signature headers must be distinct and cannot replace Base headers or transport headers');
+  if (signingKey !== undefined && typeof signingKey !== 'function')
+    throw new Error('Invalid timestamped-body signing key resolver');
+
+  return async (envelope: Envelope, timestampSeconds: string, baseKey: Uint8Array): Promise<Record<string, string>> => {
+    const timestamp = new Date(Number(timestampSeconds) * 1000).toISOString();
+    const key = signingKey === undefined ? baseKey : await signingKey(envelope);
+    const digest = await hmacBytes(key, `${timestamp}.${envelope.body}`);
+    const signature = btoa(String.fromCharCode(...digest)).replaceAll('+', '-').replaceAll('/', '_').replace(/=+$/, '');
+    return { [timestampHeader]: timestamp, [signatureHeader]: signature };
+  };
+}

package/modules/integrations/core/tokens.ts

@@ -0,0 +1,71 @@
+import { assertLabel, hex, randomId, sha256 } from './crypto.ts';
+import { IntegrationsRepository } from './repository.ts';
+import type { TokenAuthority, TokenMetadata, TokenRequestContext, TokenUsage } from './types.ts';
+function scopes(input: readonly string[]) {
+  if (!Array.isArray(input) || input.length > 100) throw new Error('Invalid scopes');
+  for (const value of input) assertLabel(value, 'scope');
+  return [...new Set(input)].sort();
+}
+function metadata(row: Record<string, unknown>): TokenMetadata {
+  return { id: String(row.id), name: String(row.name), scopes: JSON.parse(String(row.scopes)), createdAt: Number(row.created_at), expiresAt: row.expires_at === null ? null : Number(row.expires_at), revokedAt: row.revoked_at === null ? null : Number(row.revoked_at) };
+}
+export class TokenService<Context> {
+  private repository: IntegrationsRepository;
+  private authority: TokenAuthority<Context>;
+  private now: () => number;
+  constructor(repository: IntegrationsRepository, authority: TokenAuthority<Context>, now: () => number = Date.now) { this.repository = repository; this.authority = authority; this.now = now; }
+  async issue(context: Context, input: { name: string; scopes: readonly string[]; expiresAt?: number }) {
+    const requested = scopes(input.scopes), { name, expiresAt } = input;
+    const grant = await this.authority.grant(context), now = this.now();
+    // A scope ceiling read before an await is insufficient. Require the native authority
+    // snapshot's durable condition, evaluated by the INSERT itself in the fixed SQL batch.
+    if (!grant || !grant.commitGuard || typeof grant.commitGuard.sql !== 'string' || !grant.commitGuard.sql.trim()
+      || !Array.isArray(grant.commitGuard.params) || grant.commitGuard.params.some(p => p !== null && typeof p !== 'string' && (typeof p !== 'number' || !Number.isFinite(p)))) throw new Error('Token grant rejected: commit guard required');
+    const granted = scopes(grant.scopes), guard = { sql: grant.commitGuard.sql, params: [...grant.commitGuard.params] };
+    if (typeof name !== 'string' || !name || name.length > 200 || /[\x00-\x1f]/.test(name) || requested.some(scope => !granted.includes(scope))) throw new Error('Token grant rejected');
+    if (expiresAt !== undefined && (!Number.isSafeInteger(expiresAt) || expiresAt <= now)) throw new Error('Invalid token expiry');
+    const id = randomId(), token = `int_${hex(crypto.getRandomValues(new Uint8Array(32)))}`;
+    const rows = await this.repository.sql.batch([
+      { sql: `INSERT INTO integration_tokens(namespace,id,token_hash,name,scopes,created_at,expires_at) SELECT ?,?,?,?,?,?,? WHERE EXISTS(${guard.sql}) RETURNING *`, params: [this.repository.namespace, id, await sha256(token), name, JSON.stringify(requested), now, expiresAt ?? null, ...guard.params] },
+      { sql: "INSERT INTO integration_token_events(namespace,id,token_id,at,action,feature) SELECT namespace,?,id,?,'issued','integrations.tokens' FROM integration_tokens WHERE namespace=? AND id=?", params: [randomId(), now, this.repository.namespace, id] },
+    ]);
+    if (!rows[0]!.length) throw new Error('Token grant rejected: authority changed');
+    return { token, credential: metadata(rows[0]![0]!) };
+  }
+  async authorize(token: string, requiredScopes: readonly string[], context: TokenRequestContext): Promise<TokenMetadata | null> {
+    const requestId = context?.requestId, resource = context?.resource;
+    assertLabel(requestId, 'request ID'); assertLabel(resource, 'resource');
+    const required = scopes(requiredScopes), now = this.now(), id = randomId();
+    const hash = await sha256(typeof token === 'string' && token.length <= 1024 ? token : '');
+    const ns = this.repository.namespace;
+    // Authorization and its usage receipt have a single DB linearization point. Never authorize from a cached token row.
+    const rows = await this.repository.sql.batch([
+      { sql: `INSERT INTO integration_token_usage(namespace,id,token_id,at,required_scopes,request_id,resource,allowed)
+        VALUES(?,?,(SELECT id FROM integration_tokens WHERE namespace=? AND token_hash=?),?,?,?,?,
+          EXISTS(SELECT 1 FROM integration_tokens t WHERE t.namespace=? AND t.token_hash=? AND t.revoked_at IS NULL AND (t.expires_at IS NULL OR t.expires_at>?)
+            AND NOT EXISTS(SELECT value FROM json_each(?) WHERE value NOT IN (SELECT value FROM json_each(t.scopes))))) RETURNING allowed`,
+        params: [ns, id, ns, hash, now, JSON.stringify(required), requestId, resource, ns, hash, now, JSON.stringify(required)] },
+      { sql: `SELECT t.* FROM integration_tokens t JOIN integration_token_usage u ON u.namespace=t.namespace AND u.token_id=t.id WHERE u.namespace=? AND u.id=? AND u.allowed=1`, params: [ns, id] },
+    ]);
+    return rows[1]![0] ? metadata(rows[1]![0]) : null;
+  }
+  async revoke(context: Context, id: string) {
+    await this.authority.administer(context, 'revoke', id);
+    const now = this.now(), ns = this.repository.namespace;
+    const rows = await this.repository.sql.batch([
+      { sql: "INSERT INTO integration_token_events(namespace,id,token_id,at,action,feature) SELECT namespace,?,id,?,'revoked','integrations.tokens' FROM integration_tokens WHERE namespace=? AND id=? AND revoked_at IS NULL", params: [randomId(), now, ns, id] },
+      { sql: 'UPDATE integration_tokens SET revoked_at=COALESCE(revoked_at,?) WHERE namespace=? AND id=? RETURNING id', params: [now, ns, id] },
+    ]);
+    if (!rows[1]!.length) throw new Error('Token not found');
+    return { revoked: true };
+  }
+  async list(context: Context): Promise<TokenMetadata[]> {
+    await this.authority.administer(context, 'list');
+    return (await this.repository.query('SELECT * FROM integration_tokens WHERE namespace=? ORDER BY created_at,id')).map(metadata);
+  }
+  async usage(context: Context): Promise<TokenUsage[]> {
+    await this.authority.administer(context, 'usage');
+    return (await this.repository.query('SELECT * FROM integration_token_usage WHERE namespace=? ORDER BY at,id')).map(r => ({ id: String(r.id), tokenId: r.token_id === null ? null : String(r.token_id), at: Number(r.at), requiredScopes: JSON.parse(String(r.required_scopes)), allowed: r.allowed === 1,
+      requestId: r.request_id === null ? null : String(r.request_id), resource: r.resource === null ? null : String(r.resource) }));
+  }
+}

package/modules/integrations/core/types.ts

@@ -0,0 +1,52 @@
+export type DeliveryState = 'queued' | 'sending' | 'accepted' | 'rejected' | 'uncertain';
+export interface Envelope {
+  id: string; tenant: string; destinationId: string; event: string; protocol: string;
+  /** Exact UTF-8 bytes to send; never reserialize during a retry. */
+  body: string;
+}
+export interface Delivery extends Envelope {
+  fingerprint: string; destinationHash: string; state: DeliveryState; attempts: number;
+  createdAt: number; nextAt: number; claim: string | null; claimUntil: number | null;
+  maxAttempts: number; retryDelaysMs: number[];
+}
+export interface WireRequest { url: string; headers: Record<string, string>; body: string }
+export interface WireResponse { status: number; headers: Record<string, string>; body: string }
+export interface Outcome {
+  kind: 'accepted' | 'rejected' | 'retryable' | 'uncertain';
+  /** Fixed safe machine code, not raw response/error/URL/token. */
+  code: string; status?: number; retryAfterMs?: number;
+}
+export interface DeliveryProtocol {
+  id: string;
+  /** Trusted configuration lookup. Destination IDs must identify immutable versions. */
+  prepare(envelope: Envelope, now: number): Promise<WireRequest>;
+  classify(response: WireResponse, now: number): Outcome;
+}
+/** Security boundary: implementation MUST pin validated public DNS resolution to the connection,
+ * reject private/reserved IPs, require verified TLS and never follow redirects. Use NodePinnedTransport
+ * or a deployment-owned egress proxy that enforces those guarantees. Ordinary fetch is NOT sufficient. */
+export interface TrustedTransport { send(request: WireRequest): Promise<WireResponse> }
+export interface Attempt { id: string; deliveryId: string; number: number; startedAt: number; finishedAt: number | null; outcome: Outcome | null }
+export interface TokenMetadata { id: string; name: string; scopes: string[]; createdAt: number; expiresAt: number | null; revokedAt: number | null }
+/** Safe application identifiers supplied by the server handling the concrete request.
+ * Do not pass bearer tokens, secret URLs, query strings or request bodies. */
+export interface TokenRequestContext { requestId: string; resource: string }
+export interface TokenUsage {
+  id: string; tokenId: string | null; at: number; requiredScopes: string[]; allowed: boolean;
+  /** Null only for historical receipts created before request context was required. */
+  requestId: string | null; resource: string | null;
+}
+export interface TokenGrant {
+  scopes: readonly string[];
+  /** Trusted SELECT returning a row only while the authenticated issuer and the entire
+   * grant snapshot remain authorized. Bind namespace, issuer identity and the durable
+   * revision(s) read to derive scopes. Runs inside the token INSERT transaction on the
+   * repository database; all authority changes must update those rows/revisions there.
+   * Never use a constant SELECT or caller-provided SQL. No preflight-only grants. */
+  commitGuard: { sql: string; params: readonly (string | number | null)[] };
+}
+/** The consumer authenticates context on the server; never pass caller-supplied roles as authority. */
+export interface TokenAuthority<Context> {
+  grant(context: Context): Promise<TokenGrant>;
+  administer(context: Context, action: 'revoke' | 'list' | 'usage', tokenId?: string): Promise<void>;
+}

package/modules/integrations/core/upgrade-token-usage-context.sql

@@ -0,0 +1,5 @@
+-- Unnumbered expansion for consumers that applied the pre-v2 schema proposal.
+-- Apply exactly once via the consumer's migration ledger, not on fresh v2 installs.
+-- Preserve historical provenance as NULL; the v2 API requires context for every new use.
+ALTER TABLE integration_token_usage ADD COLUMN request_id TEXT;
+ALTER TABLE integration_token_usage ADD COLUMN resource TEXT;

package/modules/integrations/core/webhook.ts

@@ -0,0 +1,73 @@
+import { assertLabel, equalSignature, hmac, sha256 } from './crypto.ts';
+import type { DeliveryProtocol, Envelope, WireResponse } from './types.ts';
+import { timestampedBodySigner } from './timestamped-body-signature.ts';
+import type { TimestampedBodySignature } from './timestamped-body-signature.ts';
+export type { TimestampedBodySignature } from './timestamped-body-signature.ts';
+const wireData = (e: Envelope, timestamp: string) => JSON.stringify(['integrations.webhook.v1', e.tenant, e.destinationId, e.event, e.id, timestamp, e.body]);
+function exactBody(input: string | Uint8Array): string {
+  if (typeof input !== 'string' && !(input instanceof Uint8Array)) throw new Error('Webhook body must be a string or raw Uint8Array');
+  // Fatal decoding rejects replacement; ignoreBOM preserves a leading U+FEFF as
+  // signed content instead of silently removing its original UTF-8 bytes.
+  const body = new TextDecoder('utf-8', { fatal: true, ignoreBOM: true }).decode(
+    typeof input === 'string' ? new TextEncoder().encode(input) : input,
+  );
+  if (typeof input === 'string' && body !== input) throw new Error('Webhook body must be valid UTF-8');
+  return body;
+}
+export function retryAfter(response: WireResponse, now: number): number | undefined {
+  const value = response.headers['retry-after'];
+  if (!value) return undefined;
+  if (/^\d+$/.test(value)) return Number(value) * 1000;
+  const parsed = Date.parse(value); return Number.isFinite(parsed) ? Math.max(0, parsed - now) : undefined;
+}
+export function createWebhookProtocol(options: {
+  resolveDestination: (destinationId: string) => Promise<string>;
+  signingKey: (envelope: Envelope) => Promise<Uint8Array>;
+  timestampedBodySignature?: TimestampedBodySignature;
+}): DeliveryProtocol {
+  const signBody = options.timestampedBodySignature === undefined ? undefined : timestampedBodySigner(options.timestampedBodySignature);
+  return {
+    id: 'webhook',
+    async prepare(envelope, now) {
+      const timestamp = String(Math.floor(now / 1000));
+      const url = await options.resolveDestination(envelope.destinationId);
+      const resolvedKey = await options.signingKey(envelope);
+      if (!(resolvedKey instanceof Uint8Array) || resolvedKey.length < 32) throw new Error('HMAC key must contain at least 32 bytes');
+      // Own one snapshot before asynchronous signing so both formats use the
+      // same bytes even if the resolver's shared key rotates during preparation.
+      const key = new Uint8Array(resolvedKey);
+      const headers = {
+        'content-type': 'application/json', 'webhook-id': envelope.id,
+        'webhook-tenant': envelope.tenant, 'webhook-destination': envelope.destinationId, 'webhook-event': envelope.event,
+        'webhook-timestamp': timestamp, 'webhook-signature': `v1=${await hmac(key, wireData(envelope, timestamp))}`,
+      };
+      if (!signBody) return { url, body: envelope.body, headers };
+      exactBody(envelope.body);
+      return { url, body: envelope.body, headers: { ...headers, ...await signBody(envelope, timestamp, key) } };
+    },
+    classify(response, now) {
+      const status = response.status;
+      if (status >= 200 && status < 300) return { kind: 'accepted', code: 'webhook_accepted', status };
+      if (status === 429) return { kind: 'retryable', code: 'webhook_rate_limited', status, retryAfterMs: retryAfter(response, now) };
+      if (status >= 400 && status < 500 && status !== 408) return { kind: 'rejected', code: 'webhook_rejected', status };
+      return { kind: 'uncertain', code: 'webhook_response_uncertain', status };
+    },
+  };
+}
+export async function verifyWebhook(options: {
+  /** Receivers must pass original bytes (e.g. new Uint8Array(await request.arrayBuffer())).
+   * Strings are for already-owned canonical text, never request.text() or another lossy decode. */
+  body: string | Uint8Array; headers: Headers | Record<string, string>; key: Uint8Array;
+  tenant: string; destinationId: string; now?: number; toleranceMs?: number;
+}) {
+  const headers = options.headers instanceof Headers ? options.headers : new Headers(options.headers);
+  const read = (name: string) => { const value = headers.get(name); if (!value) throw new Error('Missing webhook header'); return value; };
+  const envelope: Envelope = { id: read('webhook-id'), tenant: read('webhook-tenant'), destinationId: read('webhook-destination'), event: read('webhook-event'), protocol: 'webhook', body: exactBody(options.body) };
+  for (const value of [envelope.id, envelope.tenant, envelope.destinationId, envelope.event]) assertLabel(value);
+  if (envelope.tenant !== options.tenant || envelope.destinationId !== options.destinationId) throw new Error('Webhook audience mismatch');
+  const timestamp = read('webhook-timestamp'), now = options.now ?? Date.now(), tolerance = options.toleranceMs ?? 300000;
+  if (!Number.isFinite(now) || !Number.isSafeInteger(tolerance) || tolerance < 1 || tolerance > 300000 || !/^\d{1,12}$/.test(timestamp) || Math.abs(now - Number(timestamp) * 1000) > tolerance) throw new Error('Webhook timestamp rejected');
+  const signature = read('webhook-signature');
+  if (!signature.startsWith('v1=') || !equalSignature(signature.slice(3), await hmac(options.key, wireData(envelope, timestamp)))) throw new Error('Webhook signature rejected');
+  return { envelope, fingerprint: await sha256(JSON.stringify(envelope)), receivedAt: now };
+}

package/modules/job-queue/README.md

@@ -0,0 +1,173 @@
+# Machine-wide development job queue
+
+Dependency-free Node 22+ library and CLI for macOS and Linux. All repositories,
+worktrees, terminals and Codex homes belonging to the same OS user coordinate in
+`~/.rer/jobs`. This uses the OS home, independent of `CODEX_HOME` and the working
+directory (even if a launcher overrides `HOME`). `RER_JOBS_DIR` selects another
+shared local directory. Cross-account scheduling requires a common execution
+identity with access to both state and private lifetime sockets; the default is
+private to its owner. Use a local filesystem with atomic hard links and rename,
+not a network filesystem. No daemon, install, service or provider is needed.
+
+```sh
+node /path/to/base/modules/job-queue/cli.mjs run --kind heavy --label 'app build' -- pnpm build
+node /path/to/base/modules/job-queue/cli.mjs run --kind heavy --priority owner --label 'Owner browser review' -- pnpm exec playwright test --workers=2
+node /path/to/base/modules/job-queue/cli.mjs status
+node /path/to/base/modules/job-queue/cli.mjs status --json
+node /path/to/base/modules/job-queue/cli.mjs drain --max-wait 30 --json
+```
+
+Run waits indefinitely unless `--max-wait SECONDS` is supplied. Expiry removes the
+request, reports the admission reason, and exits **75** (`EX_TEMPFAIL`). Command
+exit codes pass through, including 75; `--json` identifies queue expiry with
+`timedOut: true`. SIGINT returns 130 and SIGTERM returns 143. Invalid invocation
+or queue failure returns 64. Command arguments pass directly without shell
+interpolation; use `sh -c` explicitly when a shell is required. Command stdout
+and stderr are inherited. For `run --json`, the final control result is written
+to stderr; `status` and `drain` JSON use stdout. `drain` waits for an empty queue,
+reclaims dead leases and never cancels live work. It is useful in tests; ongoing
+producers can keep it waiting indefinitely.
+
+## Admission and the owner's machine rule
+
+Heavy work starts only when its request heads the ordered queue, occupied heavy
+slots are below the configured count, the one-minute OS load is at or below the
+threshold when one is set, and available memory is strictly above the floor. Defaults:
+
+| Setting in config.json | Default | Environment override |
+| --- | --- | --- |
+| slots | max(1, min(3, floor(CPUs / 4), floor(RAM / 8 GiB))) | RER_JOBS_SLOTS |
+| loadThreshold | none: a fleet sets one in its own environment | RER_JOBS_LOAD_THRESHOLD |
+| minFreeMemoryBytes | 2 GiB | RER_JOBS_MIN_FREE_MEMORY_BYTES |
+| pollMs | 3000 | RER_JOBS_POLL_MS |
+| nice | 15 | RER_JOBS_NICE |
+| killGraceMs | 1000 | RER_JOBS_KILL_GRACE_MS |
+
+Put numeric settings in `$RER_JOBS_DIR/config.json` (or `~/.rer/jobs/config.json`).
+Environment overrides take precedence. All clients should use the same policy;
+central config avoids differing limits between sessions. Resource settings are
+read when a client is created. `status` prints its effective policy, current load,
+available and raw free memory, running labels/repositories/elapsed times, ordered
+waiting jobs, and the head's admission reason. Available memory is what the OS
+can reclaim: on macOS the free, inactive, speculative and purgeable pages from
+`vm_stat` (macOS keeps little memory "free" on purpose, so `os.freemem()` reads
+0.1 to 4 GiB on an idle Mac with tens of GiB reclaimable); on Linux
+`MemAvailable`. The 2 GiB floor is below what a normal idle Mac with 16 GiB or
+more has available, and above the point where the compressor and swap start
+working hard. A waiting job reports its queue position, the jobs ahead of it
+with their repository paths, and available memory against the floor; set
+`RER_JOBS_MIN_FREE_MEMORY_BYTES` (bytes, 0 for no floor) to change it. Fleets
+that need a stricter floor set it in their own environment.
+
+FIFO is the sequence assigned at atomic enqueue. Priority classes are `owner`,
+`normal` (default), then `background`; FIFO holds within each class. Owner work
+can overtake queued normal/background jobs, but cannot preempt running commands.
+Continuous higher-priority arrivals can delay lower-priority work.
+
+The queue replaces independent load polling with coordinated admission. It
+cannot control commands launched outside it or prevent unrelated applications
+raising load after admission. Keep the owner's 15 GiB disk guard and small test
+worker counts. Agents should still run at most one heavy job per session.
+
+## State, crash recovery and cancellation
+
+`state.json` contains monotonically assigned sequence numbers, queued requests
+and running leases with PID, process start time, command, repository and label.
+Each mutation replaces a complete snapshot by atomic rename. A short Lamport
+bakery lock publishes fully written immutable contender identities by exclusive
+hard link in `locks/`; choosing/ticket changes use atomic rename. This avoids
+read-then-write admission and stale-reclaimer races against a replacement lock.
+Lock entries have unique names and are removed after the transaction. Abandoned
+temporary files from a hard crash are ignored; they carry no authority and may
+be removed when no clients are using the directory.
+
+Linux identities include boot ID and kernel start ticks. macOS uses UTC `ps` start
+time plus a random lifetime nonce served by an owned Unix socket. The nonce
+distinguishes recycled PIDs even within macOS's one-second start-time precision.
+The detached supervisor has a unique process title, also checked before sending
+group signals on both platforms. The lifetime sockets are private files in the OS temp
+directory (short `/tmp` paths if needed). Dead lease sockets are removed on
+recovery. An unavailable identity probe that cannot establish death fails closed.
+If a lifetime socket resets during shutdown, the queue rechecks PID/start: proven
+death is reclaimed, while an uncertain live owner stays held until the next
+sample. Ordinary client shutdown therefore cannot abort another queued command.
+
+A reservation initially belongs to its calling process. A separate detached
+supervisor establishes its process group and transfers its identity into the
+lease **before** receiving permission to spawn the command under `nice -n 15`.
+The command and ordinary descendants inherit that group. Normal command exit,
+SIGINT or SIGTERM triggers TERM to the entire group, followed by KILL after the
+grace interval, then releases the slot. IPC loss tells the supervisor to stop
+its group if the caller is killed. If the supervisor itself is killed, the next
+queue operation kills remaining group members before reclaiming the lease.
+PID reuse never authorizes killing a replacement group. POSIX keeps group IDs
+reserved while old group members exist ([process ID reuse](https://pubs.opengroup.org/onlinepubs/009696699/basedefs/xbd_chap04.html)).
+Node's [detached child option](https://nodejs.org/api/child_process.html#optionsdetached)
+establishes the supervisor's new group and session on these platforms.
+
+This controls descendants that remain in the command's process group. Commands
+that deliberately call `setsid`/detach into another group need their own cleanup;
+portable process groups do not provide sandbox containment. SIGKILL cannot run
+JavaScript cleanup, so recovery occurs when another client runs or through the
+surviving supervisor. Zombies are stopped processes and their OS parent/init
+must reap them. No macOS or Linux guarantee requires an installed daemon.
+Darwin can report `EPERM` for a zombie-only group; cleanup confirms that no live
+members remain before treating this as completion. A real zombie-only process
+group test covers this behavior.
+Permission failures with live members, or an unavailable inspection, retain the
+lease and report failure.
+
+Never pass credentials in command arguments: the private state records argv for
+lease inspection. Supply credentials through environment variables. Do not
+print them in labels, commands or diagnostics.
+
+## Library and CLI integration
+
+```js
+import { createQueue } from './modules/job-queue/index.mjs';
+const queue = await createQueue();
+try {
+  const result = await queue.run(['pnpm', 'verify'], {
+    kind: 'heavy', label: 'Project verification', cwd: projectDirectory,
+    // priority: 'owner', maxWait: 120, signal: abortController.signal
+  });
+  process.exitCode = result.code;
+} finally {
+  await queue.close();
+}
+```
+
+The CLI should route the actual command array for `rer verify`, `build`, `dev`
+and `preview` through `queue.run`, preserving cwd, inherited environment/stdin,
+and the returned exit code. Browser suites, dependency installs and any separate
+workerd/build steps use the same wrapper. Use one queue boundary around a whole
+workflow; wrapping a subcommand again while its parent holds the only slot would
+deadlock. Long-running dev/preview serving uses the separate managed-server cap. Only
+finite preparation holds a heavy-job slot; no persistent server may outlive a
+released job as its descendant. Avoid spawning independent unsupervised
+servers around this wrapper. No `rer` verbs are changed by this module.
+
+Tests inject `sampler: () => ({ load, availableMemoryBytes })` through the library;
+the CLI always uses actual OS samples. Library config overrides are also useful
+for isolated test directories. Call `close()` only after all operations finish.
+`pnpm verify:job-queue` runs the focused suite with file concurrency one. Its
+cross-process probes launch lightweight real children, not actual builds.
+
+## Proposed text for Codex homes' AGENTS.md
+
+This is a proposal only; no Codex home instructions were edited:
+
+> Queue bounded dependency installs, builds, verify/test/browser suites and
+> temporary wrangler/workerd resource journeys. Run those commands through
+> `node /path/to/base/modules/job-queue/cli.mjs run --kind heavy --label TEXT -- COMMAND ARGS`.
+> All sessions use the same `~/.rer/jobs` (or owner-set `RER_JOBS_DIR`); never use a
+> per-worktree queue. The queue admits only within slots, load <=36 and the memory
+> floor, and runs commands at low priority. Let it wait; use `--max-wait 1200`
+> only when a task explicitly requires a twenty-minute bounded wait. Use
+> `--priority owner` only for the owner's interactive work. Keep at least 15 GiB
+> disk free, one heavy job at a time per session, and few test workers. Wrap one
+> boundary per workflow; nested first-party commands validate and share that
+> live membership. Dev/preview queue finite preparation and use the separate
+> server registry for persistent serving. Do not hold a heavy lease for an idle
+> server or leave a server descended from a finished job. Stop servers when
+> finished. Inspect waiting reasons with `status`; do not bypass admission.

package/modules/job-queue/cli.mjs

@@ -0,0 +1,64 @@
+#!/usr/bin/env node
+import { createQueue } from './index.mjs';
+import { waitingMessage } from './waiting.mjs';
+import { fileURLToPath } from 'node:url';
+import { realpathSync } from 'node:fs';
+
+const usage = 'job-queue run --kind heavy [--label TEXT] [--priority owner|normal|background] [--max-wait SECONDS] [--json] -- <command> [args]\njob-queue status|drain [--json] [--max-wait SECONDS]';
+export function parse(args) {
+  const verb = args.shift(), options = {};
+  while (args.length && args[0] !== '--') {
+    const flag = args.shift();
+    if (flag === '--json') options.json = true;
+    else if (['--kind', '--label', '--priority', '--max-wait'].includes(flag)) {
+      if (!args.length || args[0].startsWith('--')) throw Error(`Missing value for ${flag}`);
+      options[{ '--kind': 'kind', '--label': 'label', '--priority': 'priority', '--max-wait': 'maxWait' }[flag]] = args.shift();
+    } else throw Error(`Unknown option ${flag}`);
+  }
+  if (options.maxWait !== undefined) {
+    options.maxWait = Number(options.maxWait);
+    if (!Number.isFinite(options.maxWait) || options.maxWait < 0) throw Error('max-wait must be nonnegative seconds');
+  }
+  if (!['run', 'status', 'drain'].includes(verb)) throw Error(usage);
+  if (verb === 'run' && (args.shift() !== '--' || !args.length || options.kind !== 'heavy')) throw Error(usage);
+  if (verb !== 'run' && args.length) throw Error(usage);
+  return { verb, options, command: args };
+}
+
+function render(view) {
+  const elapsed = job => Math.floor((Date.now() - (job.startedAt ?? job.enqueuedAt)) / 1000);
+  return [`Load ${view.resources.load.toFixed(2)}; available memory ${(view.resources.availableMemoryBytes / 1024 ** 3).toFixed(2)} GiB (raw free ${(view.resources.freeMemoryBytes / 1024 ** 3).toFixed(2)} GiB) against a floor of ${(view.config.minFreeMemoryBytes / 1024 ** 3).toFixed(2)} GiB; slots ${view.running.length}/${view.config.slots}`,
+    ...view.running.map(job => `Running: ${job.label} | ${job.repository} | ${elapsed(job)}s`),
+    ...view.queued.map((job, index) => `Queued ${index + 1}: ${job.label} (${job.priority}) | ${job.repository} | ${elapsed(job)}s`),
+    `Admission: ${view.admissionReason}`].join('\n');
+}
+
+function shellQuote(value) {
+  if (process.platform === 'win32') return `"${String(value).replaceAll('"', '""')}"`;
+  return `'${String(value).replaceAll("'", "'\\''")}'`;
+}
+
+async function main() {
+  const { verb, options, command } = parse(process.argv.slice(2));
+  const queue = await createQueue();
+  try {
+    let result;
+    if (verb === 'run') {
+      const statusCommand = [process.execPath, fileURLToPath(import.meta.url), 'status', '--json'].map(shellQuote).join(' ');
+      result = await queue.run(command, { ...options, onWaiting: (reason, details) => {
+        if (!options.json) console.error(`${waitingMessage(details)}\nInspect the queue with: ${statusCommand}`);
+      } });
+      if (result.timedOut) console.error(`Job queue max-wait expired: ${result.reason} (exit ${result.code})`);
+      if (result.error) console.error(result.error);
+      // Command stdout is preserved; JSON control output goes to stderr for run.
+      if (options.json) console.error(JSON.stringify(result));
+    } else {
+      result = verb === 'status' ? await queue.status() : await queue.drain(options);
+      console.log(options.json ? JSON.stringify(result) : render(result));
+      if (result.timedOut) console.error('Job queue drain max-wait expired (exit 75)');
+    }
+    process.exitCode = result.code ?? 0;
+  } finally { await queue.close(); }
+}
+if (process.argv[1] && realpathSync(process.argv[1]) === fileURLToPath(import.meta.url))
+  main().catch(error => { console.error(error.message); process.exitCode = 64; });