Identity and auth

What identity looks like in code

Two layers — the oracle's persistent identity, set once at boot via env vars; and per-user identity, validated on every request via UCAN headers.

import { createOracleApp, type OracleConfig } from '@ixo/oracle-runtime';

const config: OracleConfig = {
  name: 'My Oracle',
  org: 'My Org',
  description: 'What this oracle does.',
};

const app = await createOracleApp({ config });
// Runtime fills in `entityDid` from process.env.ORACLE_ENTITY_DID
// and builds the internal OracleIdentity used by every plugin.

The OracleConfig type lives in packages/oracle-runtime/src/plugin-api/types.ts — plugins read the resolved identity off ctx.identity (a OracleIdentity).

One-time oracle setup

qiforge-cli create-entity --no-interactive \
  --network devnet \
  --oracle-name "My Oracle" \
  --org-name "My Org" \
  --api-url http://localhost:3000 \
  --model "anthropic/claude-sonnet-4"

qiforge-cli setup-encryption-key

ORACLE_DID=did:ixo:ixo1...
ORACLE_ENTITY_DID=did:ixo:entity:...
ORACLE_NAME=My Oracle
NETWORK=devnet

MATRIX_BASE_URL=https://matrix.ixo.world
MATRIX_ORACLE_ADMIN_USER_ID=@oracle-bot:ixo.world
MATRIX_ORACLE_ADMIN_PASSWORD=...
MATRIX_ORACLE_ADMIN_ACCESS_TOKEN=...
MATRIX_ACCOUNT_ROOM_ID=...
MATRIX_VALUE_PIN=...
MATRIX_RECOVERY_PHRASE=...

SECP_MNEMONIC=...   # signs UCAN invocations to downstream services

UCAN_AUTH_MAX_TTL_SECONDS=900           # max lifetime the oracle accepts for a user auth invocation (default 15 min)
UCAN_REAUTH_PROMPT_THROTTLE_SECONDS=21600  # min gap between "please re-authorize" prompts (default 6 hours)

What the runtime loads on boot

After Matrix init completes in the background, the runtime reads two further pieces of secret material from the oracle's Matrix account room:

1. UCAN signing mnemonic — used by UcanService to mint downstream-service invocations.
2. P-256 encryption key — used by SecretsService to decrypt per-room secrets.

If a key is missing, boot logs a warning naming the CLI command to fix it. Auth-requiring routes return 401 until provisioned; non-authenticated routes (/, /health, /docs, any host or plugin authExcludedRoutes) stay reachable.

Per-request user auth

Two distinct concerns, two distinct artifacts — AuthHeaderMiddleware verifies both on every protected route:

• Authentication (who is calling) = a user-signed UCAN invocation. Short-lived, replay-bounded, sent as Authorization: Bearer <invocation> + X-Auth-Type: ucan. This is the primary auth path.
• Authorization (what the oracle may do downstream) = the user→oracle delegation, sent as x-ucan-delegation. Plugins read it to mint downstream-service invocations on the user's behalf.

When neither an invocation nor a delegation is present, the middleware returns 401 with:

Missing UCAN authentication: provide Authorization: Bearer <invocation> with X-Auth-Type: ucan, or an x-ucan-delegation header

A malformed or expired invocation returns 401 Invalid UCAN invocation.

AuthHeaderMiddleware:

Opt routes out of auth

Two mechanisms to expose public routes — host-level and plugin-level. Both merge onto the runtime's built-in exclusion list: / (the JSON landing payload), /health, /docs, and /docs/(.*).

import { RequestMethod } from '@nestjs/common';
import { createOracleApp, type AuthExcludedRoute } from '@ixo/oracle-runtime';

const HOST_AUTH_EXCLUDED_ROUTES: AuthExcludedRoute[] = [
  { path: 'version', method: RequestMethod.GET },
];

const app = await createOracleApp({
  config,
  nestModules: [VersionModule],
  authExcludedRoutes: HOST_AUTH_EXCLUDED_ROUTES,
});

override getAuthExcludedRoutes(): AuthExcludedRoute[] {
  return [{ path: 'weather/now', method: RequestMethod.GET }];
}

Any other plugin or host route returns 401 without a UCAN header — exclusion is path-and-method specific.

Mint downstream UCAN invocations

When a plugin calls a downstream service on the user's behalf, it does not reuse the user's invocation — it mints a fresh one signed by the oracle's SECP_MNEMONIC, derived from the user's stored delegation. The minted invocation goes out to the downstream service the same way the user authenticates to this oracle: Authorization: Bearer <invocation> + X-Auth-Type: ucan.

handler: async (args, rtCtx: RuntimeContext) => {
  // No signing key (mnemonic not yet provisioned) → minting is a no-op.
  if (!rtCtx.ucan.hasSigningKey()) {
    return JSON.stringify({ error: 'Oracle signing key not provisioned.' });
  }

  // Resolve the service URL to its did:web identifier, then mint against it.
  const serviceDid = await rtCtx.ucan.resolveServiceDid(
    'https://downstream-service.example',
  );
  if (!serviceDid) {
    return JSON.stringify({ error: 'Could not resolve downstream service DID.' });
  }

  const invocation = await rtCtx.ucan.mintInvocation(
    { did: serviceDid, capability: 'ixo:downstream' },
    // Claim the ability the user's delegation grants — see below.
    { can: 'downstream/*' },
  );

  const resp = await fetch('https://downstream-service.example/data', {
    headers: {
      Authorization: `Bearer ${invocation}`,
      'X-Auth-Type': 'ucan',
    },
  });
  // ...
}

The full UCAN helper surface on rtCtx.ucan:

See packages/oracle-runtime/src/modules/ucan/ for the service implementation.

Claim only what you were granted

An invocation says what the oracle is doing right now; the delegation says what the user permitted. The service accepts the invocation only if the delegation covers it — and coverage is narrower than it looks. A granted ability covers a claim when it is:

• '*' — covers everything, or
• exactly equal to the claim, or
• a prefix/* pattern matching it (memory/* covers memory/read).

Nothing else. In particular '*' is not a wildcard when you claim it — a '*' claim is satisfiable only by a '*' grant, because '*' does not start with memory/:

// delegation grants { can: 'memory/*', with: 'ixo:memory' }

// ❌ over-claim — refused: "Delegated capability not found"
await rtCtx.ucan.mintInvocation({ did, capability: 'ixo:memory' });

// ✅ claims exactly what was granted
await rtCtx.ucan.mintInvocation(
  { did, capability: 'ixo:memory' },
  { can: 'memory/*' },
);

What plugins can and cannot do

• Can: read rtCtx.user.did, rtCtx.user.matrixUserId, rtCtx.user.ucanDelegation, rtCtx.user.timezone.
• Can: call rtCtx.secrets.getIndex() / getValues() to read per-room secrets.
• Can: mint downstream invocations via rtCtx.ucan.mintInvocation.
• Cannot: override the oracle's identity per request.
• Cannot: issue UCANs as anyone other than the oracle itself.

Where to read next