@moesi/coordinator

WS6b is the optional coordination service over @moesi/registry. It adds an async grant inbox, encrypted recipient-bound approval relay, authenticated registry views, reconciliation runs, verified receipt ingestion, audit events, cursor export, CSV, verified-only budget views, and transactional signed-webhook delivery. It also includes an allowlisted RPC/bundler/passkey upstream proxy so project credentials remain server-side.

It is implemented as part of Moesi but optional for consumers to deploy or use. The registry artifacts and chain remain the source of truth.

Trust boundary

The service never accepts keys, plaintext enable signatures, serialized permission accounts, bearer handoff URLs, or session material. Approval relay accepts only ciphertext encrypted to the request developer and deletes it on the first successful fetch. The service records the supplied ciphertext digest and key identifier for audit, but does not recompute that digest and cannot install or exercise the authority inside the envelope.

Authentication is injected through TeamAuthenticator; production adapters must return actors authenticated with SIWE, passkeys, or service tokens. Team membership controls service data, while authorization over funds remains in Kernel policies.

issueTeamSession and createTeamSessionAuthenticator provide the service-side session boundary. The host issues a short-lived session only after completing its SIWE or WebAuthn ceremony; the coordinator verifies audience, expiry, and HMAC integrity without receiving the wallet or passkey private credential.

const service = new CoordinatorService({
  store: new PostgresCoordinatorStore({
    connection: { connectionString: process.env.DATABASE_URL },
  }),
  receiptVerifier: settlementReceiptVerifier,
});

export const fetch = createCoordinatorHandler({
  service,
  authenticator: siweOrPasskeyAuthenticator,
  observerFor: async (actor) => kernelObserverFor(actor.organizationId),
});

The handler uses standard Request/Response, so it can be mounted in Node, Bun, or another web runtime with Node-compatible PostgreSQL support. Send an Idempotency-Key header on every mutation. Keys are scoped by organization and operation; an exact retry returns the committed response, while reusing a key for another request fails with 409.

startCoordinatorNodeServer makes the handler directly runnable on Node. FileCoordinatorStore is the durable reference for single-process self-hosted mode: transactions load once and commit registry, approval, event, idempotency, and outbox state with one atomic rename. PostgresCoordinatorStore is the multi-process production adapter. It runs idempotent migrations, enforces organization-scoped transaction views, and uses row locks plus SKIP LOCKED for concurrent outbox workers.

Every lifecycle mutation commits its audit event and generic outbox message in the same transaction. drainCoordinatorOutbox atomically leases ready messages, retries with exponential backoff, recovers leases after crashes, and moves exhausted work to dead-letter. Delivery remains at-least-once; consumers dedupe with the stable event/message ID. deliverWebhook signs the exact JSON.stringify(event) body and sends that event ID as the consumer key.

The supported lifecycle is request → pending grant → active permission → revoking/closed, plus completed or expired closure. Activation requires a real four-byte Kernel permission ID. Revocation confirmation atomically closes the grant and balances approved/spent/unused amounts. Receipt ingestion validates grant status, organization attribution, chain, token/native asset, and purpose before and after external settlement verification.

Budget views sum only finalized, verified receipts for the approved asset and grant. They remain labeled advisory: aggregate accounting reports observed spend and does not replace Kernel policy enforcement.

createUpstreamProxy resolves endpoints exclusively from server configuration, caps request bodies, allowlists JSON-RPC methods, strips upstream headers, and never writes request payloads to the store or audit log. This matters because UserOperation and passkey payloads may contain signatures even though the service never persists them.

Portal fallback

The original recipient-bound URL-hash exchange remains valid. If WS6b is down, clients exchange the same encrypted artifact out of band and continue directly through @moesi/settlement; no chain state or authority lives only here. encodeApprovalHandoffFragment and decodeApprovalHandoffFragment implement that client-side fallback. The fragment contains the encrypted envelope (ciphertext plus non-secret routing/algorithm metadata), never plaintext authority, and browser URL fragments are not sent to the HTTP service.

See RUNBOOK.md for database recovery, owner rotation, Kernel-version pinning, revocation incidents, history lookback gaps, and lost coordinator state.