Skip to main content

Architecture overview

Ujex is Firebase-native agent trust infrastructure. Cloud Functions authenticate each caller, check current authority, apply policy and budget gates, and write evidence to Firestore.

One-line mental model​

Firebase Auth identifies humans and agents, callable functions enforce the trust boundary, Firestore holds control-plane records, and signed exports make the evidence portable.

Topology​

Human dashboard ── Firebase ID token ─┐
Agent SDK ─ device/scoped key session ├─► Cloud Functions ─► Firestore audit + control state
Ruzayo mail bridge ─ raw-body HMAC ───┘          │
                                                 ├─► Secret Manager / Cloud KMS
                                                 ├─► Cloud Storage (artifacts and memory bytes)
                                                 └─► Ruzayo / registered tools / signed webhooks

All deployed functions are in us-central1. Browser and SDK clients normally use the Firebase callable protocol; the mail bridge and public verification feeds use explicit HTTP handlers.

Authentication boundaries​

  • Humans sign in with Firebase Auth. Owner callables verify ownership or a named team role.
  • Agents exchange a device or scoped key through session. The returned Firebase custom token becomes an ID token carrying the agent, owner, credential kind, scopes, and session version.
  • Protected agent actions re-read the credential and current mandate. A revoked key, expired/revoked mandate, suspended agent, or stale session version fails closed.
  • Admin operators use a separate origin and an allowlisted, verified Firebase account.
  • Mail and webhook handlers verify HMAC signatures over the exact body and reject replays.

Request bodies never choose the authenticated agent. The verified token does.

Evidence flow​

Security-relevant actions append to the global audit/{seq} chain. Each row links to the prior hash. verifyChain and the hourly verifier detect a broken link; hourly anchors publish the latest verified root through the public anchors feed. Anchors are not independently retained by another operator yet, so the chain is tamper-evident—not tamper-proof against the Ujex project administrator.

Exports package JSONL records, a canonical manifest, signature material, trust instructions, and explicit custody/gap statements. Verification can run locally without uploading pack bytes.

Mail flow​

  1. Ruzayo accepts mail and sends a signed ingest request to postboxIngest.
  2. Ujex resolves the provisioned mailbox, rejects replay, scores prompt-injection risk, and records the message.
  3. Agent reads use the authenticated agent identity; owners read only owned mailboxes.
  4. Outbound work is drafted, risk checked, and—when required—held for a human decision.
  5. The scheduled dispatcher sends only eligible rows through Ruzayo and records outcomes.

Mailbox provisioning is durable and retried independently of identity creation. An agent can exist while its mailbox is honestly reported as pending or unavailable.

Operational principles​

  • Firestore transactions protect decisions, idempotency claims, and chain appends.
  • Credentials and refresh tokens are encrypted and injected server-side; list APIs return metadata, never plaintext.
  • Scheduled work uses Cloud Scheduler-backed functions and durable Firestore state.
  • Public claims are limited by the honest limits.

Where to go next​