@oxy.so/core 1.18.0 → 3.0.0

package/src/mixins/OxyServices.utility.ts

@@ -1,1803 +0,0 @@
-/**
- * Utility Methods Mixin
- *
- * Provides utility methods including Express.js authentication middleware.
- */
-import { jwtDecode } from 'jwt-decode';
-import type { JsonWebKey } from 'node:crypto';
-import type { ApiError, User } from '../models/interfaces';
-import type { OxyServicesBase } from '../OxyServices.base';
-import { loadNodeCrypto } from '@oxy.so/protocol';
-import { buildUrl } from '../utils/apiUtils';
-import { logger } from '../logger';
-import { CACHE_TIMES } from './mixinHelpers';
-import { OXY_SERVICE_ENVIRONMENTS, type OxyServiceEnvironment } from '../utils/oxyServiceEnvironment';
-
-interface JwtPayload {
-  exp?: number;
-  userId?: string;
-  id?: string;
-  sessionId?: string;
-  type?: string;
-  appId?: string;
-  credentialId?: string;
-  ownerAccountId?: string;
-  appName?: string;
-  scopes?: string[];
-  tier?: string;
-  aud?: string | string[];
-  iss?: string;
-  environment?: string;
-  nbf?: number;
-  [key: string]: unknown;
-}
-
-/**
- * Result from the service-acting-as verification endpoint.
- * Confirms that a given service app holds an active delegation grant for
- * the supplied user, along with the explicit scope list the grant covers.
- *
- * The API side stores this as an ordinary `app_grants` row — the SAME revocable
- * record the OAuth consent screen writes and the "Connected apps" UI lists and
- * deletes — whose `scopes` name `acting-as:offline`. There is deliberately no
- * separate delegation table: a second store would be a second revocation
- * surface, and a user who disconnects an application in "Connected apps" means
- * it, so one revoke has to end everything.
- *
- * `scopes` is what THAT USER consented to, not what the application may do in
- * general. `requireScope` intersects it with the token's own app-wide scopes for
- * a delegated request, and the intersection is the effective authority.
- *
- * The SDK never inspects the grant directly — it round-trips through
- * `GET /internal/service-acting-as/verify?appId=...&userId=...` so the
- * authoritative store stays server-side.
- */
-export interface ServiceActingAsVerification {
-  authorized: boolean;
-  scopes: string[];
-}
-
-/** The SET `events` member Oxy uses for an account deletion. */
-export const OXY_ACCOUNT_DELETED_EVENT_URI = 'https://oxy.so/events/account.deleted';
-
-/**
- * A verified account event from Oxy (OxyHQ/Mention#1169): a person deleted
- * their Oxy account and every relying application must erase what it holds
- * for them. Returned by `verifyAccountEvent` only after the signature, `typ`,
- * issuer and audience all check out.
- */
-export interface OxyAccountEvent {
-  /** The event id (`jti`). Stable across webhook retries and the pull feed: dedupe on it. */
-  eventId: string;
-  type: 'account.deleted';
-  /** The deleted Oxy account. */
-  userId: string;
-  /**
-   * The account's handle at deletion time, for relying parties that address
-   * the person by handle (an ActivityPub actor URI). `null` when the account had
-   * none, or when the token predates the field.
-   */
-  username: string | null;
-  /** ISO-8601 time the deletion committed. */
-  occurredAt: string;
-  /** `true` when Oxy archived the row to keep financial records. Erase either way. */
-  retained: boolean;
-  /** The application the event was addressed to (`aud`). */
-  applicationId: string;
-  /** Seconds since the epoch the token was issued at (`iat`). */
-  issuedAt: number;
-}
-
-/** One entry of the account-event pull feed (`GET /account-events`). */
-export interface OxyAccountEventFeedItem {
-  eventId: string;
-  type: 'account.deleted';
-  userId: string;
-  username: string | null;
-  occurredAt: string;
-  retained: boolean;
-  /** The same signed token the webhook carries. Verify it with `verifyAccountEvent`. */
-  token: string;
-}
-
-export interface OxyAccountEventFeedPage {
-  events: OxyAccountEventFeedItem[];
-  /** Pass back as `after` to continue; unchanged when the page is empty. */
-  nextCursor: string | null;
-}
-
-export interface VerifyAccountEventOptions {
-  /**
-   * The application id the token must be addressed to. Defaults to the `appId`
-   * of this client's configured service credential.
-   */
-  audience?: string;
-  /** Defaults to `/.well-known/jwks.json` on this client's API origin. */
-  jwksUrl?: string;
-}
-
-/** Why an account event token was refused. `message` never contains the token. */
-export class OxyAccountEventError extends Error {
-  constructor(message: string) {
-    super(message);
-    this.name = 'OxyAccountEventError';
-  }
-}
-
-/**
- * Service app metadata attached to requests authenticated with service tokens.
- *
- * Every field comes from the token's SIGNED payload and is populated only after
- * the signature, `iss`/`aud`/`type` binding and expiry all pass — so a verifier
- * holding this object can name the responsible principals without a lookup of
- * its own. Together with `credentialId` and `ownerAccountId` it is the canonical
- * attribution tuple of ADR 0007 minus the delegated user.
- *
- * `scopes` are the EFFECTIVE scopes: the credential's own scopes intersected
- * with the owning application's grant at mint time (the API's `intersectScopes`
- * is the single authority for that intersection — nothing re-intersects here).
- * Route-level checks narrow further via `requireScope()`.
- *
- * A delegated end user is NOT a field of this type, and must never become one.
- * It lives in `req.serviceActingAs` / `req.userId`, is authorised per request,
- * and is attribution only.
- */
-export interface ServiceApp {
-  appId: string;
-  appName: string;
-  scopes: string[];
-  /**
-   * `internal` when the caller is one of Oxy's own applications: app to app it
-   * is trusted outright — {@link requireScope} passes and it may act for a user
-   * without a delegation grant. `external` keeps every scope and grant rule.
-   * What the USER may do (their accounts, plan, limits) is still for the
-   * receiving service to decide. A token without the claim reads as `external`.
-   */
-  tier: 'internal' | 'external';
-  /** The credentialId of the specific service credential that minted this token. */
-  credentialId: string;
-  /**
-   * The Oxy account that owns `appId` and is financially responsible for it.
-   * The BILLING principal — never a user id, and never the delegated
-   * `X-Oxy-User-Id` (ADR 0007).
-   */
-  ownerAccountId: string;
-  /** Test/live isolation (F2.0): which `ApplicationCredential.environment` minted this token. */
-  environment: OxyServiceEnvironment;
-}
-
-/**
- * Why a request's credential was refused, recorded on the request itself.
- *
- * The middleware answers a fixed, deliberately uninformative body to the
- * client; this is the other half of that trade. A refusal is ALWAYS observable
- * to the HOST: it is logged at `warn` with a stable `code`, handed to
- * `onRefusal`, and left on `req.oxyAuthRefusal` for the host's own logs.
- *
- * It exists because the opposite cost was measured: Oxy served
- * `{"keys":[]}` from `/.well-known/jwks.json` with no Ed25519 signing key
- * bound, every service token failed `Oxy service-token key set is unavailable`,
- * and on the OPTIONAL path that failure fell straight through to `next()`.
- * The host then answered its own generic 401 and logged nothing at all, so the
- * one fact that named the fault — an empty key set — existed nowhere. Hours.
- *
- * **Nothing here is ever sent to a client, and `reason` never contains the
- * token, a signature, a secret or a session id.** It carries the SDK's own
- * failure message (`kid` unknown, audience mismatch, key set unavailable) plus
- * the ids already considered safe to log elsewhere in this middleware.
- */
-export interface OxyAuthRefusal {
-  /** Stable, greppable code. Matches the `code` a non-optional refusal answers. */
-  code: string;
-  /** Which credential lane refused. */
-  stage: 'token' | 'service-token' | 'session';
-  /** Human-readable cause. Never a token, signature, secret or session id. */
-  reason: string;
-  /** The status a NON-optional mount would have answered with. */
-  status: number;
-  /**
-   * `true` when the middleware was mounted with `optional: true`, so this
-   * refusal did not produce a response — the request continued unauthenticated
-   * and whatever the host does next (typically its own generic 401) is the
-   * only thing the client sees.
-   */
-  optional: boolean;
-}
-
-/**
- * Expected JWT audience for tokens issued by the Oxy auth service.
- */
-const OXY_JWT_AUDIENCE = 'oxy-api';
-/**
- * Expected JWT issuer for tokens issued by the Oxy auth service.
- */
-const OXY_JWT_ISSUER = 'oxy-auth';
-
-/**
- * Sentinel error classes for service-token verification. Using classes (not
- * message strings) makes the catch site below safe to extend: a new failure
- * mode added later cannot silently fall through to the generic 500 branch.
- */
-class ServiceTokenStructureError extends Error {
-  constructor(message = 'Service token has malformed structure') {
-    super(message);
-    this.name = 'ServiceTokenStructureError';
-  }
-}
-
-class ServiceTokenSignatureError extends Error {
-  constructor(message = 'Service token signature is invalid') {
-    super(message);
-    this.name = 'ServiceTokenSignatureError';
-  }
-}
-
-class ServiceTokenConfigurationError extends Error {
-  constructor(message: string) {
-    super(message);
-    this.name = 'ServiceTokenConfigurationError';
-  }
-}
-
-class ServiceTokenClaimError extends Error {
-  constructor(message: string) {
-    super(message);
-    this.name = 'ServiceTokenClaimError';
-  }
-}
-
-function isOxyServiceEnvironment(value: unknown): value is OxyServiceEnvironment {
-  return (
-    typeof value === 'string' &&
-    (OXY_SERVICE_ENVIRONMENTS as readonly string[]).includes(value)
-  );
-}
-
-/**
- * Options for oxyClient.auth() middleware
- */
-interface AuthMiddlewareOptions {
-  /** Enable debug logging (default: false) */
-  debug?: boolean;
-  /** Custom error handler - receives error object, can return response */
-  onError?: (error: ApiError) => unknown;
-  /** Load full user profile from API (default: false for performance) */
-  loadUser?: boolean;
-  /** Optional auth - attach user if token present but don't block (default: false) */
-  optional?: boolean;
-  /**
-   * Called whenever a PRESENTED credential is refused, on the optional path as
-   * well as the blocking one. Runs before the response (if any) and after
-   * `req.oxyAuthRefusal` is set, so a host can raise its own alert or carry the
-   * code into its request log. Throwing from it is swallowed — an observer must
-   * not be able to turn a refusal into a 500.
-   *
-   * Refusal is about a credential that was offered and rejected: a request with
-   * NO `Authorization` header is not refused and does not reach this.
-   */
-  onRefusal?: (refusal: OxyAuthRefusal) => void;
-  /**
-   * Public JWKS endpoint used for Ed25519 service-token verification. Defaults
-   * to `/.well-known/jwks.json` on this Oxy client's configured API origin.
-   */
-  serviceTokenJwksUrl?: string;
-  /**
-   * @deprecated Oxy-API-only transition for pre-cutover HS256 service tokens.
-   * External services omit this option and verify Ed25519 tokens through the
-   * public JWKS. Never distribute `ACCESS_TOKEN_SECRET`: a host holding it can
-   * mint user access tokens as well as verify legacy service tokens.
-   */
-  jwtSecret?: string;
-  /**
-   * Expected JWT issuer. Defaults to `'oxy-auth'`. Override only if you run
-   * a private fork of the Oxy auth server under a different `iss` claim.
-   */
-  expectedIssuer?: string;
-  /**
-   * Expected JWT audience. Defaults to `'oxy-api'`. Override only if your
-   * private fork mints tokens for a different audience.
-   */
-  expectedAudience?: string;
-}
-
-export function OxyServicesUtilityMixin<T extends typeof OxyServicesBase>(Base: T) {
-  return class extends Base {
-    /**
-     * In-memory cache for service-acting-as verification.
-     * Negative results are cached for 1min to avoid hammering the verify
-     * endpoint when a service is misconfigured; positive grants are cached
-     * for 5min to amortize the round-trip without holding stale grants too long.
-     * @internal
-     */
-    _serviceActingAsCache = new Map<string, { result: ServiceActingAsVerification | null; expiresAt: number }>();
-    /** @internal Per-client public-key cache; never contains private material. */
-    _serviceTokenJwksCache: ServiceTokenJwksCache = { keys: new Map(), expiresAt: 0, lastAttemptAt: 0 };
-
-    // TypeScript's mixin pattern requires `(...args: any[])` here — the
-    // constructor signature is a structural shape check the compiler enforces.
-    // Matches every other mixin in this package; do not change without a
-    // monorepo-wide refactor of the mixin pipeline.
-    constructor(...args: any[]) {
-      super(...(args as [any]));
-    }
-
-    /**
-     * Verify that a service app holds an active delegation grant authorising
-     * it to act on behalf of `userId`. Returns the grant (with allowed scopes)
-     * on success or `null` if no valid grant exists. Negative answers are
-     * cached briefly to protect the verify endpoint from misconfigured callers.
-     *
-     * Implemented as a per-instance Map keyed by `appId:userId`. Cached
-     * positive grants live for 5 minutes (acceptable staleness window for an
-     * impersonation grant); revocations propagate within that window.
-     *
-     * @internal Used by the auth() middleware — not part of the public API
-     */
-    async verifyServiceActingAs(
-      appId: string,
-      userId: string,
-    ): Promise<ServiceActingAsVerification | null> {
-      const cacheKey = `${appId}:${userId}`;
-      const now = Date.now();
-
-      const cached = this._serviceActingAsCache.get(cacheKey);
-      if (cached && cached.expiresAt > now) {
-        return cached.result;
-      }
-
-      try {
-        // The verify endpoint is service-to-service and admits only a
-        // platform-TRUSTED calling application, so this call must carry the
-        // VERIFIER's own service token. Sent explicitly rather than through
-        // `makeServiceRequest`, which would drop `retry: false` and the timeout
-        // — and those two are not incidental: this runs inside request-handling
-        // middleware, so an inner retry loop multiplies the latency of every
-        // delegated request by the number of attempts.
-        //
-        // A verifier with no service credentials configured throws here and
-        // lands in the catch below, which is the correct outcome. A host that
-        // cannot prove who it is has no business being told which users have
-        // delegated to which applications, and the 60s negative cache stops a
-        // misconfigured deployment from turning every request into a round trip.
-        const serviceToken = await (this as unknown as OxyAuthInstance).getServiceToken();
-
-        const result = await this.makeRequest<ServiceActingAsVerification>(
-          'GET',
-          '/internal/service-acting-as/verify',
-          { appId, userId },
-          {
-            cache: false,
-            retry: false,
-            timeout: 5000,
-            headers: { Authorization: `Bearer ${serviceToken}` },
-          },
-        );
-
-        const authorized = Boolean(result && result.authorized);
-        const verified: ServiceActingAsVerification | null = authorized
-          ? { authorized: true, scopes: Array.isArray(result.scopes) ? result.scopes : [] }
-          : null;
-
-        this._serviceActingAsCache.set(cacheKey, {
-          result: verified,
-          expiresAt: now + 5 * 60 * 1000,
-        });
-
-        return verified;
-      } catch (error) {
-        logger.warn('[oxy.auth] verifyServiceActingAs lookup failed — caching negative result', {
-          component: 'auth',
-          method: 'verifyServiceActingAs',
-          appId,
-          userId,
-        }, error);
-        // Negative cache prevents a runaway loop if the verify endpoint is
-        // down, while still letting a real grant become visible within 60s.
-        this._serviceActingAsCache.set(cacheKey, {
-          result: null,
-          expiresAt: now + 1 * 60 * 1000,
-        });
-        return null;
-      }
-    }
-
-    /**
-     * Verify an account event token from Oxy — the body of an account-event
-     * webhook, or an entry's `token` from `listAccountEvents` — and return the
-     * event. Throws {@link OxyAccountEventError} unless the token is an
-     * EdDSA-signed `secevent+jwt` from Oxy's published key set, issued by
-     * `oxy-auth`, addressed to this application, carrying exactly one known
-     * event. A service token (`typ: JWT`) is refused here, as this token is
-     * refused as a service token.
-     *
-     * Node only (it needs `node:crypto`). The caller must still be idempotent on
-     * `eventId`: Oxy delivers at least once, by push and by pull.
-     */
-    async verifyAccountEvent(
-      token: string,
-      options: VerifyAccountEventOptions = {},
-    ): Promise<OxyAccountEvent> {
-      if (typeof token !== 'string' || token.length === 0 || token.length > 16 * 1024) {
-        throw new OxyAccountEventError('Account event token is missing or oversized');
-      }
-      const parts = token.split('.');
-      if (parts.length !== 3 || parts.some((part) => part.length === 0)) {
-        throw new OxyAccountEventError('Account event token is not a compact JWS');
-      }
-      const [headerB64, payloadB64, signatureB64] = parts as [string, string, string];
-      let header: Record<string, unknown>;
-      let payload: Record<string, unknown>;
-      try {
-        header = parseJsonSegment(headerB64);
-        payload = parseJsonSegment(payloadB64);
-      } catch {
-        throw new OxyAccountEventError('Account event token is malformed');
-      }
-      if (
-        Object.keys(header).length !== 3
-        || header.alg !== 'EdDSA'
-        || header.typ !== 'secevent+jwt'
-        || typeof header.kid !== 'string'
-        || !/^[A-Za-z0-9._-]{1,128}$/.test(header.kid)
-      ) {
-        throw new OxyAccountEventError('Account event token header is not supported');
-      }
-
-      const nodeCrypto = await loadNodeCrypto();
-      let jwk: ServiceTokenPublicJwk;
-      try {
-        jwk = await resolveServiceTokenPublicKey(
-          header.kid,
-          options.jwksUrl ?? new URL('/.well-known/jwks.json', this.getBaseURL()).toString(),
-          this._serviceTokenJwksCache,
-        );
-      } catch (error) {
-        throw new OxyAccountEventError(
-          error instanceof Error ? error.message.replace('Service token', 'Account event') : 'Signing key is unavailable',
-        );
-      }
-      const signature = Buffer.from(signatureB64, 'base64url');
-      if (signature.toString('base64url') !== signatureB64 || signature.length !== 64) {
-        throw new OxyAccountEventError('Account event token signature is malformed');
-      }
-      let verified = false;
-      try {
-        const publicKey = nodeCrypto.createPublicKey({ key: jwk as unknown as JsonWebKey, format: 'jwk' });
-        verified = nodeCrypto.verify(null, Buffer.from(`${headerB64}.${payloadB64}`), publicKey, signature);
-      } catch {
-        verified = false;
-      }
-      if (!verified) throw new OxyAccountEventError('Account event token signature is invalid');
-
-      if (payload.iss !== OXY_JWT_ISSUER) {
-        throw new OxyAccountEventError('Account event token issuer is not Oxy');
-      }
-      const audience = options.audience ?? await this._configuredServiceAppId();
-      if (typeof payload.aud !== 'string' || payload.aud !== audience) {
-        throw new OxyAccountEventError('Account event token is addressed to another application');
-      }
-      if (typeof payload.jti !== 'string' || payload.jti.length === 0 || payload.jti.length > 128) {
-        throw new OxyAccountEventError('Account event token has no event id');
-      }
-      if (typeof payload.iat !== 'number' || !Number.isFinite(payload.iat)) {
-        throw new OxyAccountEventError('Account event token has no issue time');
-      }
-      const events = payload.events;
-      if (typeof events !== 'object' || events === null || Array.isArray(events)) {
-        throw new OxyAccountEventError('Account event token carries no events');
-      }
-      const entries = Object.entries(events as Record<string, unknown>);
-      const deleted = (events as Record<string, unknown>)[OXY_ACCOUNT_DELETED_EVENT_URI];
-      if (entries.length !== 1 || typeof deleted !== 'object' || deleted === null || Array.isArray(deleted)) {
-        throw new OxyAccountEventError('Account event token carries an unknown event');
-      }
-      const body = deleted as Record<string, unknown>;
-      if (typeof body.userId !== 'string' || body.userId.length === 0 || body.userId.length > 128) {
-        throw new OxyAccountEventError('Account event names no account');
-      }
-      if (typeof body.occurredAt !== 'string' || Number.isNaN(Date.parse(body.occurredAt))) {
-        throw new OxyAccountEventError('Account event has no occurrence time');
-      }
-      if (body.username !== undefined && body.username !== null && typeof body.username !== 'string') {
-        throw new OxyAccountEventError('Account event username is malformed');
-      }
-      return {
-        eventId: payload.jti,
-        type: 'account.deleted',
-        userId: body.userId,
-        username: typeof body.username === 'string' ? body.username : null,
-        occurredAt: body.occurredAt,
-        retained: body.retained === true,
-        applicationId: payload.aud,
-        issuedAt: payload.iat,
-      };
-    }
-
-    /**
-     * One page of account events addressed to this application, oldest first,
-     * from Oxy's pull feed — the reconciliation path behind the webhook. Needs
-     * the service credential (`configureServiceAuth`). Verify each entry's
-     * `token` with {@link verifyAccountEvent} before acting on it.
-     */
-    async listAccountEvents(
-      options: { after?: string; limit?: number } = {},
-    ): Promise<OxyAccountEventFeedPage> {
-      const serviceToken = await (this as unknown as OxyAuthInstance).getServiceToken();
-      const query: Record<string, string> = {};
-      if (options.after) query.after = options.after;
-      if (options.limit !== undefined) query.limit = String(options.limit);
-      return this.makeRequest<OxyAccountEventFeedPage>('GET', '/account-events', query, {
-        cache: false,
-        headers: { Authorization: `Bearer ${serviceToken}` },
-      });
-    }
-
-    /** @internal The `appId` claim of this client's own service token. */
-    async _configuredServiceAppId(): Promise<string> {
-      const serviceToken = await (this as unknown as OxyAuthInstance).getServiceToken();
-      const appId = jwtDecode<JwtPayload>(serviceToken).appId;
-      if (typeof appId !== 'string' || appId.length === 0) {
-        throw new OxyAccountEventError('No audience given and the service credential names no application');
-      }
-      return appId;
-    }
-
-    /**
-     * Express.js authentication middleware
-     *
-     * Validates JWT tokens against the Oxy API and attaches user data to requests.
-     * Uses server-side session validation for security (not just JWT decode).
-     *
-     * **Design note — jwtDecode vs jwt.verify:**
-     * This middleware uses `jwtDecode()` (decode-only, NO signature check) for
-     * user tokens, because third-party apps mounting `oxy.auth()` do not hold
-     * the Oxy signing secret. **Every claim in a user token is therefore
-     * attacker-controlled and proves nothing on its own.** The identity comes
-     * from somewhere else entirely:
-     * - A user token MUST carry a `sessionId`. That session is validated
-     *   server-side on every request via `validateSession()`, and the user id
-     *   is read off the VALIDATED SESSION — never off the token. A token whose
-     *   `userId` claim disagrees with the session is refused
-     *   (`SESSION_USER_MISMATCH`); a token with no `sessionId` at all is
-     *   refused outright (`SESSION_REQUIRED`). There is no local-claims path.
-     * - Service tokens (type: 'service') ARE stateless, so they use Ed25519
-     *   verification against Oxy's public JWKS and are additionally checked
-     *   for `aud`, `iss`, `type`, time, attribution and scope claims. The
-     *   `jwtSecret` path exists only for Oxy API's bounded HS256 transition.
-     * - The backend's own `authMiddleware` uses `jwt.verify()` because it has
-     *   direct access to `ACCESS_TOKEN_SECRET`.
-     *
-     * **Why session-less user tokens are refused rather than trusted:**
-     * every user access token the Oxy API issues carries a `sessionId` (see
-     * `packages/api/src/utils/sessionUtils.ts`, `generateSessionTokens` — the
-     * only mint site for user tokens, including the OAuth code exchange). So
-     * refusing session-less user tokens costs nothing legitimate, while
-     * accepting them let anyone authenticate as anyone by hand-rolling a JWT
-     * with a `userId` claim and a garbage signature.
-     *
-     * **Why the claimed user id is cross-checked against the session:**
-     * `GET /session/validate/:sessionId` is UNAUTHENTICATED and does not bind
-     * the bearer token — it returns whoever owns the session id it was handed.
-     * Trusting the token's `userId` claim after a successful validation would
-     * therefore let a caller holding ANY live session id (their own, for
-     * instance) pair it with a forged `userId` and be trusted as that user.
-     * `authSocket()` has always cross-checked this; the HTTP middleware now
-     * does too.
-     *
-     * **Service-token delegation (X-Oxy-User-Id):**
-     * When a service token is accompanied by `X-Oxy-User-Id`, the SDK calls
-     * `verifyServiceActingAs(appId, userId)` to confirm an explicit delegation
-     * grant exists before attaching `req.userId`. A missing/expired grant
-     * results in a 403 — there is no fail-open path.
-     *
-     * @example
-     * ```typescript
-     * import { OxyServices } from '@oxy.so/core';
-     *
-     * const oxy = new OxyServices({ baseURL: 'https://api.oxy.so' });
-     *
-     * // Protect all routes under /protected
-     * app.use('/protected', oxy.auth());
-     *
-     * // Access user in route handler
-     * app.get('/protected/me', (req, res) => {
-     *   res.json({ userId: req.userId, user: req.user });
-     * });
-     *
-     * // Load full user profile from API
-     * app.use('/admin', oxy.auth({ loadUser: true }));
-     *
-     * // Optional auth - attach user if present, don't block if absent
-     * app.use('/public', oxy.auth({ optional: true }));
-     *
-     * // Require a specific scope on a service-token-protected route
-     * app.use('/internal/files', oxy.serviceAuth(), oxy.requireScope('files:write'));
-     * ```
-     *
-     * @param options Optional configuration
-     * @returns Express middleware function
-     */
-    auth(options: AuthMiddlewareOptions = {}) {
-      const {
-        debug = false,
-        onError,
-        onRefusal,
-        loadUser = false,
-        optional = false,
-        jwtSecret,
-        serviceTokenJwksUrl = new URL('/.well-known/jwks.json', this.getBaseURL()).toString(),
-        expectedIssuer = OXY_JWT_ISSUER,
-        expectedAudience = OXY_JWT_AUDIENCE,
-      } = options;
-      // Cross-mixin method access: typed as a structural subset of the
-      // composed OxyServices we know we have at runtime.
-      const oxyInstance = this as unknown as OxyAuthInstance;
-
-      /**
-       * Make a refusal observable to the HOST, without telling the client
-       * anything it is not already told.
-       *
-       * Called at the top of every branch that rejects a PRESENTED credential,
-       * including the ones `optional` then swallows — those are the expensive
-       * ones, because they leave no trace anywhere else. The response bodies
-       * below are untouched by design: what a client sees does not change.
-       *
-       * `warn`, not `debug`: a debug-gated reason is only there for whoever
-       * already suspects this middleware, and the failure mode this exists for
-       * is the one where nobody does. The volume is bounded by refusals, and a
-       * host drowning in them has a fault worth the lines.
-       */
-      const recordRefusal = (
-        req: AuthReq,
-        refusal: { code: string; stage: OxyAuthRefusal['stage']; reason: string; status: number },
-      ): void => {
-        const recorded: OxyAuthRefusal = { ...refusal, optional };
-        req.oxyAuthRefusal = recorded;
-        logger.warn(`[oxy.auth] refused ${recorded.code}: ${recorded.reason}`, {
-          component: 'auth',
-          method: 'auth',
-          code: recorded.code,
-          stage: recorded.stage,
-          reason: recorded.reason,
-          status: recorded.status,
-          // Says whether the client will see this status or the host's own
-          // generic answer — the difference that made the JWKS outage invisible.
-          optional: recorded.optional,
-          path: req.path,
-        });
-        if (onRefusal) {
-          try {
-            onRefusal(recorded);
-          } catch (observerError) {
-            logger.warn('[oxy.auth] onRefusal observer threw', {
-              component: 'auth',
-              method: 'auth',
-            }, observerError);
-          }
-        }
-      };
-
-      // Return an async middleware function
-      return async (req: AuthReq, res: AuthRes, next: AuthNext) => {
-        try {
-          // Extract token from Authorization header.
-          // Node/Express normalizes `Authorization` to a string; we guard
-          // against the (legal but unusual) string[] case anyway.
-          const rawAuthHeader = req.headers.authorization;
-          const authHeader = Array.isArray(rawAuthHeader) ? rawAuthHeader[0] : rawAuthHeader;
-          const token = authHeader?.startsWith('Bearer ') ? authHeader.substring(7) : null;
-
-          if (debug) {
-            logger.debug(`[oxy.auth] ${req.method} ${req.path} | token: ${!!token}`, {
-              component: 'auth',
-              method: 'auth',
-            });
-          }
-
-          if (!token) {
-            if (optional) {
-              req.userId = null;
-              req.user = null;
-              return next();
-            }
-
-            const error = {
-              error: 'MISSING_TOKEN',
-              message: 'Access token required',
-              code: 'MISSING_TOKEN',
-              status: 401
-            };
-            if (onError) return onError(error);
-            return res.status(401).json(error);
-          }
-
-          // Decode token to extract claims
-          let decoded: JwtPayload;
-          try {
-            decoded = jwtDecode<JwtPayload>(token);
-          } catch (decodeError) {
-            recordRefusal(req, {
-              code: 'INVALID_TOKEN_FORMAT',
-              stage: 'token',
-              reason: 'Bearer credential is not a decodable JWT',
-              status: 401,
-            });
-            if (debug) {
-              logger.debug('[oxy.auth] Token decode failed', {
-                component: 'auth',
-                method: 'auth',
-              }, decodeError);
-            }
-            if (optional) {
-              req.userId = null;
-              req.user = null;
-              return next();
-            }
-
-            const error = {
-              error: 'INVALID_TOKEN_FORMAT',
-              message: 'Invalid token format',
-              code: 'INVALID_TOKEN_FORMAT',
-              status: 401
-            };
-            if (onError) return onError(error);
-            return res.status(401).json(error);
-          }
-
-          // Handle service tokens (internal service-to-service auth)
-          // Service tokens are stateless JWTs with type: 'service' — requires signature verification
-          if (decoded.type === 'service') {
-            // Verify JWT signature, then audience / issuer / type / appId claims.
-            //
-            // Signature verification uses Node crypto rather than
-            // `jsonwebtoken` because this file also ships into RN/web bundles.
-            // The middleware itself runs on Node hosts; `loadNodeCrypto` is
-            // per-platform, so Metro never bundles a Node built-in reference.
-            try {
-              await verifyServiceTokenSignature(token, {
-                legacySecret: jwtSecret,
-                jwksUrl: serviceTokenJwksUrl,
-                cache: this._serviceTokenJwksCache,
-              });
-              verifyServiceTokenClaims(decoded, {
-                audience: expectedAudience,
-                issuer: expectedIssuer,
-              });
-            } catch (verifyError) {
-              // Structure + signature + claim errors all map to 401. Anything
-              // else (e.g. Node crypto failing to load on a misconfigured host)
-              // genuinely IS a 500.
-              if (
-                verifyError instanceof ServiceTokenConfigurationError
-              ) {
-                recordRefusal(req, {
-                  code: 'SERVICE_TOKEN_NOT_CONFIGURED',
-                  stage: 'service-token',
-                  reason: verifyError.message,
-                  status: 403,
-                });
-                if (optional) {
-                  req.userId = null;
-                  req.user = null;
-                  return next();
-                }
-                const error = {
-                  error: 'SERVICE_TOKEN_NOT_CONFIGURED',
-                  message: verifyError.message,
-                  code: 'SERVICE_TOKEN_NOT_CONFIGURED',
-                  status: 403,
-                };
-                if (onError) return onError(error);
-                return res.status(403).json(error);
-              }
-              if (
-                verifyError instanceof ServiceTokenStructureError ||
-                verifyError instanceof ServiceTokenSignatureError ||
-                verifyError instanceof ServiceTokenClaimError
-              ) {
-                const code = verifyError instanceof ServiceTokenClaimError
-                  ? 'INVALID_SERVICE_TOKEN_CLAIMS'
-                  : 'INVALID_SERVICE_TOKEN';
-                // The SDK's own message is the whole diagnostic value here —
-                // "signing key is unknown" (rotated/unpublished kid), "key set
-                // is unavailable" (JWKS empty, unreachable or malformed) and
-                // "audience mismatch" are three different outages that answer
-                // the client identically.
-                recordRefusal(req, {
-                  code,
-                  stage: 'service-token',
-                  reason: `${verifyError.name}: ${verifyError.message}`,
-                  status: 401,
-                });
-                if (debug) {
-                  logger.debug('[oxy.auth] Service token rejected', {
-                    component: 'auth',
-                    method: 'auth.serviceToken',
-                    reason: verifyError.name,
-                    detail: verifyError.message,
-                  });
-                }
-                if (optional) {
-                  req.userId = null;
-                  req.user = null;
-                  return next();
-                }
-                const error = {
-                  error: code,
-                  message: verifyError.message,
-                  code,
-                  status: 401,
-                };
-                if (onError) return onError(error);
-                return res.status(401).json(error);
-              }
-
-              logger.error('[oxy.auth] Unexpected error during service token verification', verifyError, {
-                component: 'auth',
-                method: 'auth.serviceToken',
-              });
-              const error = {
-                error: 'AUTH_INTERNAL_ERROR',
-                message: 'Internal authentication error',
-                code: 'AUTH_INTERNAL_ERROR',
-                status: 500,
-              };
-              if (onError) return onError(error);
-              return res.status(500).json(error);
-            }
-
-            // Check expiration — reject tokens at exact expiry second (use <=)
-            const now = Math.floor(Date.now() / 1000);
-            if (!Number.isInteger(decoded.exp) || (decoded.exp as number) <= now) {
-              recordRefusal(req, {
-                code: 'TOKEN_EXPIRED',
-                stage: 'service-token',
-                reason: Number.isInteger(decoded.exp)
-                  ? 'Service token expired'
-                  : 'Service token has no integer exp claim',
-                status: 401,
-              });
-              if (optional) {
-                req.userId = null;
-                req.user = null;
-                return next();
-              }
-              const error = { error: 'TOKEN_EXPIRED', message: 'Service token expired', code: 'TOKEN_EXPIRED', status: 401 };
-              if (onError) return onError(error);
-              return res.status(401).json(error);
-            }
-            if (decoded.nbf !== undefined && (!Number.isInteger(decoded.nbf) || decoded.nbf > now)) {
-              recordRefusal(req, {
-                code: 'INVALID_SERVICE_TOKEN_CLAIMS',
-                stage: 'service-token',
-                reason: 'Service token is not yet valid (nbf)',
-                status: 401,
-              });
-              const error = { error: 'INVALID_SERVICE_TOKEN_CLAIMS', message: 'Service token is not yet valid', code: 'INVALID_SERVICE_TOKEN_CLAIMS', status: 401 };
-              if (onError) return onError(error);
-              return res.status(401).json(error);
-            }
-
-            // Validate required service token fields. All of them are
-            // required, `ownerAccountId` included: an optional billing
-            // principal is one fallback away from being resolved from the
-            // delegated user, which is the exact confusion ADR 0007 forbids.
-            const appId = decoded.appId;
-            const credentialId = decoded.credentialId;
-            const ownerAccountId = decoded.ownerAccountId;
-            const environment = decoded.environment;
-            if (
-              !isExactNonEmptyServiceClaim(appId) ||
-              !isExactNonEmptyServiceClaim(decoded.appName) ||
-              !isExactNonEmptyServiceClaim(credentialId) ||
-              !isExactNonEmptyServiceClaim(ownerAccountId) ||
-              !isOxyServiceEnvironment(environment)
-              || !Array.isArray(decoded.scopes)
-              || !decoded.scopes.every((scope) => typeof scope === 'string' && scope.length > 0 && scope === scope.trim())
-              || new Set(decoded.scopes).size !== decoded.scopes.length
-            ) {
-              recordRefusal(req, {
-                code: 'INVALID_SERVICE_TOKEN',
-                stage: 'service-token',
-                // Names the field rather than its value: an exact-match claim
-                // failing on invisible whitespace reads as "present" in a log
-                // that only says which claims were missing.
-                reason: `Service token claims unusable (${[
-                  !isExactNonEmptyServiceClaim(appId) ? 'appId' : null,
-                  !isExactNonEmptyServiceClaim(decoded.appName) ? 'appName' : null,
-                  !isExactNonEmptyServiceClaim(credentialId) ? 'credentialId' : null,
-                  !isExactNonEmptyServiceClaim(ownerAccountId) ? 'ownerAccountId' : null,
-                  !isOxyServiceEnvironment(environment) ? 'environment' : null,
-                  !Array.isArray(decoded.scopes) ? 'scopes' : null,
-                ].filter((field) => field !== null).join(', ') || 'scopes'})`,
-                status: 401,
-              });
-              if (optional) {
-                req.userId = null;
-                req.user = null;
-                return next();
-              }
-              const error = { error: 'INVALID_SERVICE_TOKEN', message: 'Invalid service token: missing required claims', code: 'INVALID_SERVICE_TOKEN', status: 401 };
-              if (onError) return onError(error);
-              return res.status(401).json(error);
-            }
-
-            const tier: ServiceApp['tier'] = decoded.tier === 'internal' ? 'internal' : 'external';
-
-            // Read delegated user ID from header
-            const oxyUserIdRaw = req.headers['x-oxy-user-id'];
-            const oxyUserId = isExactNonEmptyServiceClaim(oxyUserIdRaw) ? oxyUserIdRaw : null;
-            if (oxyUserIdRaw !== undefined && oxyUserId === null) {
-              recordRefusal(req, {
-                code: 'INVALID_SERVICE_TOKEN_CLAIMS',
-                stage: 'service-token',
-                reason: 'X-Oxy-User-Id is not an exact non-empty id',
-                status: 401,
-              });
-              const error = {
-                error: 'INVALID_SERVICE_TOKEN_CLAIMS',
-                message: 'Delegated user id must be an exact non-empty id',
-                code: 'INVALID_SERVICE_TOKEN_CLAIMS',
-                status: 401,
-              };
-              if (onError) return onError(error);
-              return res.status(401).json(error);
-            }
-
-            // One of Oxy's own applications acts for a user without a grant:
-            // inside the ecosystem that is trust, not consent. It still acts
-            // with the USER's authority only — what that user may do is for the
-            // receiving service to check.
-            if (oxyUserId && tier === 'internal') {
-              req.userId = oxyUserId;
-              req.user = { id: oxyUserId } as User;
-              req.serviceActingAs = { userId: oxyUserId, scopes: [] };
-            } else if (oxyUserId) {
-              // C3: an EXTERNAL service may only act as a user when an explicit
-              // ServiceActingAs grant exists for that (appId, userId) pair.
-              // Without the grant we MUST refuse — silently attaching
-              // `req.userId = oxyUserId` would let any service impersonate
-              // any user simply by setting the header.
-              const grant = await oxyInstance.verifyServiceActingAs(appId, oxyUserId);
-              if (!grant || !grant.authorized) {
-                logger.warn('[oxy.auth] Service token rejected — no delegation grant', {
-                  component: 'auth',
-                  method: 'auth.serviceToken',
-                  appId,
-                  attemptedUserId: oxyUserId,
-                });
-                // A verifier with no service credentials of its own cannot
-                // reach the verify endpoint at all, so `null` here can mean
-                // "no grant" OR "this host cannot ask". Both refuse, and both
-                // are worth naming on the request.
-                recordRefusal(req, {
-                  code: 'SERVICE_ACTING_AS_UNAUTHORIZED',
-                  stage: 'service-token',
-                  reason: `No delegation grant for app ${appId} acting as ${oxyUserId} (or this verifier could not reach the grant check)`,
-                  status: 403,
-                });
-                const error = {
-                  error: 'SERVICE_ACTING_AS_UNAUTHORIZED',
-                  message: 'Service not authorized to act as this user',
-                  code: 'SERVICE_ACTING_AS_UNAUTHORIZED',
-                  status: 403,
-                };
-                if (onError) return onError(error);
-                return res.status(403).json(error);
-              }
-
-              // ATTRIBUTION ONLY. `req.userId` answers "on whose behalf", never
-              // "who pays": the billing principal stays `req.serviceApp
-              // .ownerAccountId`, which this branch does not touch. Read it
-              // through `getOxyBillingPrincipal` (`@oxy.so/core/server`), whose
-              // return type a user id cannot satisfy (ADR 0007).
-              req.userId = oxyUserId;
-              req.user = { id: oxyUserId } as User;
-              req.serviceActingAs = { userId: oxyUserId, scopes: grant.scopes };
-            } else {
-              // No X-Oxy-User-Id means the service is acting as itself.
-              req.userId = null;
-              req.user = null;
-            }
-
-            req.accessToken = token;
-            req.serviceApp = {
-              appId,
-              appName: decoded.appName,
-              credentialId,
-              ownerAccountId,
-              scopes: Array.isArray(decoded.scopes) ? decoded.scopes : [],
-              environment,
-              tier,
-            };
-
-            if (debug) {
-              logger.debug(`[oxy.auth] Service token OK app=${decoded.appName} delegateUser=${oxyUserId || '(none)'}`, {
-                component: 'auth',
-                method: 'auth.serviceToken',
-              });
-            }
-
-            return next();
-          }
-
-          // The CLAIMED user id. Never trusted as an identity — it is only ever
-          // compared against the id the validated session resolves to.
-          const claimedUserId = readStringClaim(decoded.userId) ?? readStringClaim(decoded.id);
-          if (!claimedUserId) {
-            recordRefusal(req, {
-              code: 'INVALID_TOKEN_PAYLOAD',
-              stage: 'token',
-              reason: 'Token carries no usable user id claim',
-              status: 401,
-            });
-            if (optional) {
-              req.userId = null;
-              req.user = null;
-              return next();
-            }
-
-            const error = {
-              error: 'INVALID_TOKEN_PAYLOAD',
-              message: 'Token missing user ID',
-              code: 'INVALID_TOKEN_PAYLOAD',
-              status: 401
-            };
-            if (onError) return onError(error);
-            return res.status(401).json(error);
-          }
-
-          // Check token expiration locally first (fast path)
-          // Reject tokens at exact expiry second (use <=)
-          if (decoded.exp && decoded.exp <= Math.floor(Date.now() / 1000)) {
-            recordRefusal(req, {
-              code: 'TOKEN_EXPIRED',
-              stage: 'token',
-              reason: 'User access token expired',
-              status: 401,
-            });
-            if (optional) {
-              req.userId = null;
-              req.user = null;
-              return next();
-            }
-
-            const error = {
-              error: 'TOKEN_EXPIRED',
-              message: 'Token expired',
-              code: 'TOKEN_EXPIRED',
-              status: 401
-            };
-            if (onError) return onError(error);
-            return res.status(401).json(error);
-          }
-
-          // A server-validated session is MANDATORY for a user token. The JWT
-          // signature is not verified on this path, so a bare decoded token
-          // proves nothing: without the session round-trip a forged token could
-          // claim any user id. Mirrors `authSocket()`, which has always
-          // required this.
-          const sessionId = readStringClaim(decoded.sessionId);
-          if (!sessionId) {
-            recordRefusal(req, {
-              code: 'SESSION_REQUIRED',
-              stage: 'token',
-              reason: 'User access token is not bound to a session',
-              status: 401,
-            });
-            if (optional) {
-              req.userId = null;
-              req.user = null;
-              return next();
-            }
-
-            const error = {
-              error: 'SESSION_REQUIRED',
-              message: 'Access token is not bound to a session',
-              code: 'SESSION_REQUIRED',
-              status: 401
-            };
-            if (onError) return onError(error);
-            return res.status(401).json(error);
-          }
-
-          // Validate the token against the Oxy API. This proves the session is
-          // real and unrevoked, AND yields the identity it belongs to.
-          try {
-            const validationResult = await oxyInstance.validateSession(sessionId, {
-              useHeaderValidation: true,
-            });
-
-            if (!validationResult || !validationResult.valid || !validationResult.user) {
-              recordRefusal(req, {
-                code: 'INVALID_SESSION',
-                stage: 'session',
-                reason: 'Session is invalid, revoked or expired',
-                status: 401,
-              });
-              if (optional) {
-                req.userId = null;
-                req.user = null;
-                return next();
-              }
-
-              const error = {
-                error: 'INVALID_SESSION',
-                message: 'Session invalid or expired',
-                code: 'INVALID_SESSION',
-                status: 401
-              };
-              if (onError) return onError(error);
-              return res.status(401).json(error);
-            }
-
-            // The session — not the token — is the source of truth for identity.
-            const validatedUserId = getUserIdentityId(validationResult.user);
-            if (!validatedUserId) {
-              recordRefusal(req, {
-                code: 'INVALID_SESSION',
-                stage: 'session',
-                reason: 'Session did not resolve to a usable identity',
-                status: 401,
-              });
-              if (optional) {
-                req.userId = null;
-                req.user = null;
-                return next();
-              }
-
-              const error = {
-                error: 'INVALID_SESSION',
-                message: 'Session did not resolve to a usable identity',
-                code: 'INVALID_SESSION',
-                status: 401
-              };
-              if (onError) return onError(error);
-              return res.status(401).json(error);
-            }
-
-            if (validatedUserId !== claimedUserId) {
-              // Session-id/claim confusion: the caller presented a live session
-              // that belongs to somebody else. Worth a warning — it has no
-              // benign cause. Ids only; never the token or the payload.
-              logger.warn('[oxy.auth] Token rejected — claimed user does not own the session', {
-                component: 'auth',
-                method: 'auth',
-                claimedUserId,
-                validatedUserId,
-              });
-              recordRefusal(req, {
-                code: 'SESSION_USER_MISMATCH',
-                stage: 'session',
-                reason: 'Token user claim does not own the presented session',
-                status: 401,
-              });
-
-              if (optional) {
-                req.userId = null;
-                req.user = null;
-                return next();
-              }
-
-              const error = {
-                error: 'SESSION_USER_MISMATCH',
-                message: 'Token user does not match the session',
-                code: 'SESSION_USER_MISMATCH',
-                status: 401
-              };
-              if (onError) return onError(error);
-              return res.status(401).json(error);
-            }
-
-            req.userId = validatedUserId;
-            req.accessToken = token;
-            req.sessionId = sessionId;
-            // Session validation already returned the full user, so `loadUser`
-            // costs no extra round-trip.
-            req.user = loadUser ? validationResult.user : ({ id: validatedUserId } as User);
-
-            if (debug) {
-              logger.debug(`[oxy.auth] OK user=${validatedUserId} session=${sessionId}`, {
-                component: 'auth',
-                method: 'auth',
-              });
-            }
-
-            return next();
-          } catch (validationError) {
-            recordRefusal(req, {
-              code: 'SESSION_VALIDATION_ERROR',
-              stage: 'session',
-              // Name and transport code only. The message of a failed
-              // `validateSession` can carry the request URL, and that URL
-              // contains the session id — which is a credential.
-              reason: `Session validation call failed (${describeErrorSafely(validationError)})`,
-              status: 401,
-            });
-            if (debug) {
-              logger.debug('[oxy.auth] Session validation failed', {
-                component: 'auth',
-                method: 'auth',
-              }, validationError);
-            }
-
-            if (optional) {
-              req.userId = null;
-              req.user = null;
-              return next();
-            }
-
-            const error = {
-              error: 'SESSION_VALIDATION_ERROR',
-              message: 'Session validation failed',
-              code: 'SESSION_VALIDATION_ERROR',
-              status: 401
-            };
-            if (onError) return onError(error);
-            return res.status(401).json(error);
-          }
-        } catch (error) {
-          const handled = oxyInstance.handleError(error) as Error & {
-            code?: string;
-            status?: number;
-            details?: Record<string, unknown>;
-          };
-          const apiError: ApiError = {
-            message: handled.message || 'Authentication error',
-            code: handled.code ?? 'AUTH_ERROR',
-            status: handled.status ?? 500,
-            details: handled.details,
-          };
-
-          if (debug) {
-            logger.debug('[oxy.auth] Error', {
-              component: 'auth',
-              method: 'auth',
-            }, apiError);
-          }
-
-          if (onError) return onError(apiError);
-          return res.status(apiError.status).json(apiError);
-        }
-      };
-    }
-
-    /**
-     * Socket.IO authentication middleware factory
-     *
-     * Returns a middleware function for Socket.IO that validates JWT tokens
-     * from the handshake auth object and attaches user data to the socket.
-     *
-     * Uses `jwtDecode()` + API session validation (same rationale as `auth()`).
-     *
-     * @example
-     * ```typescript
-     * import { OxyServices } from '@oxy.so/core';
-     * import { Server } from 'socket.io';
-     *
-     * const oxy = new OxyServices({ baseURL: 'https://api.oxy.so' });
-     * const io = new Server(server);
-     *
-     * // Authenticate all socket connections
-     * io.use(oxy.authSocket());
-     *
-     * io.on('connection', (socket) => {
-     *   console.log('Authenticated user:', socket.data.userId);
-     * });
-     * ```
-     */
-    authSocket(options: { debug?: boolean } = {}) {
-      const { debug = false } = options;
-      // Cross-mixin method access typed via the same structural subset.
-      const oxyInstance = this as unknown as OxyAuthInstance;
-
-      return async (socket: SocketLike, next: (err?: Error) => void) => {
-        try {
-          const token = socket.handshake?.auth?.token;
-
-          if (!token) {
-            return next(new Error('Authentication required'));
-          }
-
-          let decoded: JwtPayload;
-          try {
-            decoded = jwtDecode<JwtPayload>(token);
-          } catch (decodeError) {
-            if (debug) {
-              logger.debug('[oxy.authSocket] Token decode failed', {
-                component: 'auth',
-                method: 'authSocket',
-              }, decodeError);
-            }
-            return next(new Error('Invalid token'));
-          }
-
-          const claimedUserId = readStringClaim(decoded.userId) ?? readStringClaim(decoded.id);
-          if (!claimedUserId) {
-            return next(new Error('Invalid token payload'));
-          }
-
-          // Check expiration — reject tokens at exact expiry second (use <=)
-          if (decoded.exp && decoded.exp <= Math.floor(Date.now() / 1000)) {
-            return next(new Error('Token expired'));
-          }
-
-          // A server-validated session is mandatory. A bare decoded JWT proves
-          // nothing — the signature is not verified here, so without a session
-          // round-trip a forged token could claim any user id.
-          const sessionId = readStringClaim(decoded.sessionId);
-          if (!sessionId) {
-            return next(new Error('Session required'));
-          }
-
-          let userId = claimedUserId;
-          try {
-            const result = await oxyInstance.validateSession(sessionId, {
-              useHeaderValidation: true,
-            });
-            if (!result || !result.valid || !result.user) {
-              return next(new Error('Session invalid'));
-            }
-
-            // The session is the source of truth. The client-claimed user id
-            // must match the server-validated identity, otherwise a valid
-            // session could be paired with a forged user id.
-            const validatedUserId = getUserIdentityId(result.user);
-            if (!validatedUserId || validatedUserId !== claimedUserId) {
-              return next(new Error('Session user mismatch'));
-            }
-
-            userId = validatedUserId;
-          } catch (validateErr) {
-            if (debug) {
-              logger.debug('[oxy.authSocket] Session validation failed', {
-                component: 'auth',
-                method: 'authSocket',
-              }, validateErr);
-            }
-            return next(new Error('Session validation failed'));
-          }
-
-          // Attach user data to socket. We expose BOTH `socket.data.userId`
-          // (the official Socket.IO data slot) and `socket.user` because
-          // every consumer in this ecosystem (Mention, Allo, api/server.ts)
-          // reads from `socket.user.id`.
-          socket.data = socket.data || {};
-          socket.data.userId = userId;
-          socket.data.sessionId = sessionId;
-          socket.data.token = token;
-
-          socket.user = { id: userId, userId, sessionId };
-
-          if (debug) {
-            logger.debug(`[oxy.authSocket] OK user=${userId}`, {
-              component: 'auth',
-              method: 'authSocket',
-            });
-          }
-
-          next();
-        } catch (err) {
-          if (debug) {
-            logger.debug('[oxy.authSocket] Error', {
-              component: 'auth',
-              method: 'authSocket',
-            }, err);
-          }
-          next(new Error('Authentication error'));
-        }
-      };
-    }
-    /**
-     * Express.js middleware that only allows service tokens.
-     * Use this for internal-only endpoints that should not be accessible
-     * to regular users or API key consumers.
-     *
-     * @example
-     * ```typescript
-     * // Protect internal endpoints
-     * app.use('/internal', oxy.serviceAuth());
-     *
-     * app.post('/internal/trigger', (req, res) => {
-     *   console.log('Service app:', req.serviceApp);
-     *   console.log('Acting on behalf of user:', req.userId);
-     * });
-     * ```
-     */
-    serviceAuth(options: {
-      debug?: boolean;
-      /** Observe refusals on the service lane; forwarded straight to `auth()`. */
-      onRefusal?: (refusal: OxyAuthRefusal) => void;
-      /** @deprecated Oxy-API-only HS256 transition; external verifiers use JWKS. */
-      jwtSecret?: string;
-      serviceTokenJwksUrl?: string;
-      expectedIssuer?: string;
-      expectedAudience?: string;
-    } = {}) {
-      const innerAuth = this.auth({ ...options });
-
-      return async (req: AuthReq, res: AuthRes, next: AuthNext) => {
-        await innerAuth(req, res, () => {
-          if (!req.serviceApp) {
-            return res.status(403).json({
-              error: 'Service token required',
-              message: 'This endpoint is only accessible to internal services',
-              code: 'SERVICE_TOKEN_REQUIRED',
-            });
-          }
-          next();
-        });
-      };
-    }
-
-    /**
-     * Express.js middleware that enforces a specific service-token scope.
-     *
-     * Mount AFTER `auth()` / `serviceAuth()` — relies on `req.serviceApp` and
-     * (when delegation is in effect) `req.serviceActingAs.scopes`. App-only
-     * service requests require the app scope. Delegated user requests require
-     * BOTH the app scope and the per-user delegation scope.
-     *
-     * The intersection is the point, not a redundancy, because the two scope
-     * lists answer different questions and neither implies the other:
-     *
-     *   `serviceApp.scopes`      what the PLATFORM allows this application to do
-     *                            (credential ∩ application ceiling, at mint time)
-     *   `serviceActingAs.scopes` what THIS USER allowed it to do (`app_grants`)
-     *
-     * Requiring only the app scope would let an application do to a user
-     * something that user never consented to; requiring only the grant would let
-     * a user hand an application authority staff never gave it, so a revoked
-     * platform scope would keep working for every user who had already
-     * consented. Effective authority is the intersection, and this is where it
-     * is taken.
-     *
-     * Requests authenticated as a regular user (no service token) are rejected
-     * with 403 — scope-protected endpoints are service-to-service by design.
-     *
-     * @example
-     * ```typescript
-     * app.use(
-     *   '/internal/files',
-     *   oxy.serviceAuth(),
-     *   oxy.requireScope('files:write'),
-     * );
-     * ```
-     */
-    requireScope(scope: string) {
-      if (typeof scope !== 'string' || scope.length === 0) {
-        throw new Error('requireScope: scope must be a non-empty string');
-      }
-
-      return (req: AuthReq, res: AuthRes, next: AuthNext): void => {
-        const appScopes = req.serviceApp?.scopes ?? [];
-        const delegatedScopes = req.serviceActingAs?.scopes ?? [];
-
-        if (!req.serviceApp) {
-          res.status(403).json({
-            error: 'SERVICE_TOKEN_REQUIRED',
-            message: 'Scope-protected endpoint requires a service token',
-            code: 'SERVICE_TOKEN_REQUIRED',
-            status: 403,
-          });
-          return;
-        }
-
-        // Oxy's own applications are trusted app to app; scopes are the
-        // external lane.
-        if (req.serviceApp.tier === 'internal') {
-          next();
-          return;
-        }
-
-        const appHasScope = appScopes.includes(scope);
-        const delegationHasScope = delegatedScopes.includes(scope);
-        const hasRequiredScope = req.serviceActingAs
-          ? appHasScope && delegationHasScope
-          : appHasScope;
-
-        if (hasRequiredScope) {
-          next();
-          return;
-        }
-
-        logger.warn('[oxy.auth] Service token missing required scope', {
-          component: 'auth',
-          method: 'requireScope',
-          appId: req.serviceApp.appId,
-          required: scope,
-        });
-        res.status(403).json({
-          error: 'INSUFFICIENT_SCOPE',
-          message: `Required scope '${scope}' not granted`,
-          code: 'INSUFFICIENT_SCOPE',
-          status: 403,
-        });
-      };
-    }
-  };
-}
-
-// ---------------------------------------------------------------------------
-// Service token verification helpers
-// ---------------------------------------------------------------------------
-
-interface ServiceTokenPublicJwk {
-  readonly kty: 'OKP';
-  readonly crv: 'Ed25519';
-  readonly x: string;
-  readonly use: 'sig';
-  readonly alg: 'EdDSA';
-  readonly kid: string;
-}
-
-function isExactNonEmptyServiceClaim(value: unknown): value is string {
-  return typeof value === 'string' && value.length > 0 && value.trim() === value;
-}
-
-interface ServiceTokenJwksCache {
-  keys: Map<string, ServiceTokenPublicJwk>;
-  expiresAt: number;
-  lastAttemptAt: number;
-  pending?: Promise<void>;
-}
-
-const JWKS_CACHE_MS = 5 * 60 * 1000;
-const JWKS_UNKNOWN_KID_REFRESH_MS = 60 * 1000;
-const JWKS_FETCH_TIMEOUT_MS = 5_000;
-const JWKS_MAX_BYTES = 64 * 1024;
-const JWKS_MAX_KEYS = 20;
-
-function parseJsonSegment(segment: string): Record<string, unknown> {
-  if (!/^[A-Za-z0-9_-]+$/.test(segment)) throw new ServiceTokenStructureError('Service token segment is not base64url');
-  const bytes = Buffer.from(segment, 'base64url');
-  if (bytes.toString('base64url') !== segment) throw new ServiceTokenStructureError('Service token segment is not canonical base64url');
-  try {
-    const value = JSON.parse(bytes.toString('utf8')) as unknown;
-    if (typeof value !== 'object' || value === null || Array.isArray(value)) throw new Error('not an object');
-    return value as Record<string, unknown>;
-  } catch {
-    throw new ServiceTokenStructureError('Service token segment is not a JSON object');
-  }
-}
-
-function parseServiceTokenJwks(value: unknown): Map<string, ServiceTokenPublicJwk> {
-  if (typeof value !== 'object' || value === null || Array.isArray(value)) throw new ServiceTokenSignatureError('Oxy JWKS is malformed');
-  const keys = (value as { keys?: unknown }).keys;
-  if (!Array.isArray(keys) || keys.length === 0 || keys.length > JWKS_MAX_KEYS) throw new ServiceTokenSignatureError('Oxy JWKS has an invalid key set');
-  const result = new Map<string, ServiceTokenPublicJwk>();
-  for (const value of keys) {
-    if (typeof value !== 'object' || value === null || Array.isArray(value)) throw new ServiceTokenSignatureError('Oxy JWKS contains a malformed key');
-    const key = value as Record<string, unknown>;
-    if (
-      key.kty !== 'OKP'
-      || key.crv !== 'Ed25519'
-      || typeof key.x !== 'string'
-      || key.x.length === 0
-      || key.use !== 'sig'
-      || key.alg !== 'EdDSA'
-      || typeof key.kid !== 'string'
-      || !/^[A-Za-z0-9._-]{1,128}$/.test(key.kid)
-      || Object.prototype.hasOwnProperty.call(key, 'd')
-      || result.has(key.kid)
-    ) throw new ServiceTokenSignatureError('Oxy JWKS contains an unsupported or duplicate key');
-    const x = Buffer.from(key.x, 'base64url');
-    if (x.length !== 32 || x.toString('base64url') !== key.x) {
-      throw new ServiceTokenSignatureError('Oxy JWKS contains an invalid Ed25519 key');
-    }
-    result.set(key.kid, key as unknown as ServiceTokenPublicJwk);
-  }
-  return result;
-}
-
-async function refreshServiceTokenJwks(url: string, cache: ServiceTokenJwksCache): Promise<void> {
-  if (cache.pending) return cache.pending;
-  cache.lastAttemptAt = Date.now();
-  cache.pending = (async () => {
-    const controller = new AbortController();
-    const timeout = setTimeout(() => controller.abort(), JWKS_FETCH_TIMEOUT_MS);
-    try {
-      const response = await fetch(url, {
-        method: 'GET',
-        headers: { accept: 'application/json' },
-        signal: controller.signal,
-        redirect: 'error',
-      });
-      if (!response.ok) throw new ServiceTokenSignatureError(`Oxy JWKS returned HTTP ${response.status}`);
-      const source = await response.text();
-      if (Buffer.byteLength(source, 'utf8') > JWKS_MAX_BYTES) throw new ServiceTokenSignatureError('Oxy JWKS exceeds the size limit');
-      cache.keys = parseServiceTokenJwks(JSON.parse(source) as unknown);
-      cache.expiresAt = Date.now() + JWKS_CACHE_MS;
-    } finally {
-      clearTimeout(timeout);
-    }
-  })();
-  try {
-    await cache.pending;
-  } finally {
-    cache.pending = undefined;
-  }
-}
-
-async function resolveServiceTokenPublicKey(
-  kid: string,
-  url: string,
-  cache: ServiceTokenJwksCache,
-): Promise<ServiceTokenPublicJwk> {
-  const now = Date.now();
-  const cached = cache.keys.get(kid);
-  if (cached && cache.expiresAt > now) return cached;
-  const mayRefresh = cache.expiresAt <= now || now - cache.lastAttemptAt >= JWKS_UNKNOWN_KID_REFRESH_MS;
-  if (mayRefresh) {
-    try {
-      await refreshServiceTokenJwks(url, cache);
-    } catch {
-      const stillValid = cache.keys.get(kid);
-      if (stillValid && cache.expiresAt > Date.now()) return stillValid;
-      throw new ServiceTokenSignatureError('Oxy service-token key set is unavailable');
-    }
-  }
-  const resolved = cache.keys.get(kid);
-  if (!resolved || cache.expiresAt <= Date.now()) throw new ServiceTokenSignatureError('Service token signing key is unknown');
-  return resolved;
-}
-
-/** Ed25519/JWKS verification with an Oxy-API-only HS256 transition. */
-async function verifyServiceTokenSignature(
-  token: string,
-  options: { legacySecret?: string; jwksUrl: string; cache: ServiceTokenJwksCache },
-): Promise<void> {
-  const nodeCrypto = await loadNodeCrypto();
-  const parts = token.split('.');
-  if (parts.length !== 3) {
-    throw new ServiceTokenStructureError(`Service token must have 3 parts, got ${parts.length}`);
-  }
-  const [headerB64, payloadB64, signatureB64] = parts;
-  if (!headerB64 || !payloadB64 || !signatureB64) {
-    throw new ServiceTokenStructureError('Service token has empty segment');
-  }
-  const header = parseJsonSegment(headerB64);
-  if (header.alg === 'HS256') {
-    if (!options.legacySecret) throw new ServiceTokenConfigurationError('Legacy service token verification is not configured');
-    const expectedSig = nodeCrypto.createHmac('sha256', options.legacySecret)
-      .update(`${headerB64}.${payloadB64}`)
-      .digest('base64url');
-    const sigBuf = Buffer.from(signatureB64);
-    const expectedBuf = Buffer.from(expectedSig);
-    if (sigBuf.length !== expectedBuf.length || !nodeCrypto.timingSafeEqual(sigBuf, expectedBuf)) throw new ServiceTokenSignatureError();
-    return;
-  }
-  if (
-    Object.keys(header).length !== 3
-    || header.alg !== 'EdDSA'
-    || header.typ !== 'JWT'
-    || typeof header.kid !== 'string'
-    || !/^[A-Za-z0-9._-]{1,128}$/.test(header.kid)
-  ) throw new ServiceTokenStructureError('Service token JOSE header is not supported');
-  const jwk = await resolveServiceTokenPublicKey(header.kid, options.jwksUrl, options.cache);
-  let publicKey: Awaited<ReturnType<typeof nodeCrypto.createPublicKey>>;
-  try {
-    publicKey = nodeCrypto.createPublicKey({ key: jwk as unknown as JsonWebKey, format: 'jwk' });
-  } catch {
-    throw new ServiceTokenSignatureError('Service token public key is invalid');
-  }
-  const signature = Buffer.from(signatureB64, 'base64url');
-  if (signature.toString('base64url') !== signatureB64 || signature.length !== 64) throw new ServiceTokenStructureError('Service token signature is malformed');
-  if (!nodeCrypto.verify(null, Buffer.from(`${headerB64}.${payloadB64}`), publicKey, signature)) throw new ServiceTokenSignatureError();
-}
-
-/**
- * Read a JWT claim that is only usable as a non-empty string.
- *
- * A decoded payload is attacker-controlled JSON: a claim the type declares as
- * `string` can arrive as a number, an object, or `null`. Narrowing here keeps
- * those values out of URL construction and identity comparison, so an
- * unexpected shape becomes a 401 rather than a stringified surprise.
- */
-/**
- * A short, log-safe description of a thrown value: its class name and, when the
- * transport attached one, its `code` (`ECONNREFUSED`, `ETIMEDOUT`, `ENOTFOUND`
- * …). Never the message — a failed request's message can quote the URL it was
- * made against, and a session-validation URL contains the session id.
- */
-function describeErrorSafely(error: unknown): string {
-  if (!(error instanceof Error)) return typeof error;
-  const code = (error as { code?: unknown }).code;
-  return typeof code === 'string' && /^[A-Za-z0-9_]{1,40}$/.test(code)
-    ? `${error.name}: ${code}`
-    : error.name;
-}
-
-function readStringClaim(value: unknown): string | null {
-  return typeof value === 'string' && value.length > 0 ? value : null;
-}
-
-/**
- * Resolve the canonical user id from a validated session's user object.
- *
- * The API serializer emits `id`, but some upstream shapes carry the raw Mongo
- * `_id` instead. We accept either, but only a non-empty string — anything else
- * means the validated identity is unusable and the caller must reject.
- */
-function getUserIdentityId(user: User): string | null {
-  const candidate = (user as { id?: unknown; _id?: unknown }).id
-    ?? (user as { id?: unknown; _id?: unknown })._id;
-  return typeof candidate === 'string' && candidate.length > 0 ? candidate : null;
-}
-
-/**
- * Verify that a decoded service-token payload carries the expected `aud`,
- * `iss`, and `type` claims. Throws `ServiceTokenClaimError` on mismatch.
- * This is the defence against the H4 vulnerability where a recovery / 2FA /
- * access token signed by the same shared secret could be replayed as a
- * service token because no claim binding existed.
- */
-function verifyServiceTokenClaims(
-  decoded: JwtPayload,
-  expected: { audience: string; issuer: string },
-): void {
-  if (decoded.type !== 'service') {
-    throw new ServiceTokenClaimError(`Service token has unexpected type '${String(decoded.type)}'`);
-  }
-  if (decoded.iss !== expected.issuer) {
-    throw new ServiceTokenClaimError(`Service token issuer mismatch: expected '${expected.issuer}', got '${String(decoded.iss)}'`);
-  }
-  const aud = decoded.aud;
-  if (Array.isArray(aud)) {
-    if (!aud.includes(expected.audience)) {
-      throw new ServiceTokenClaimError(`Service token audience does not include '${expected.audience}'`);
-    }
-  } else if (aud !== expected.audience) {
-    throw new ServiceTokenClaimError(`Service token audience mismatch: expected '${expected.audience}', got '${String(aud)}'`);
-  }
-}
-
-// ---------------------------------------------------------------------------
-// Local request/response/socket typing
-//
-// Express's types are an optional peer (we don't want to take a hard dep on
-// `@types/express` from a platform-agnostic SDK). The structural subset below
-// captures everything this middleware actually touches, so consumers get type
-// checking without us coupling to Express's full surface.
-// ---------------------------------------------------------------------------
-
-interface AuthReq {
-  method?: string;
-  path?: string;
-  headers: Record<string, string | string[] | undefined>;
-  query?: Record<string, unknown>;
-  userId?: string | null;
-  user?: User | null;
-  accessToken?: string;
-  sessionId?: string | null;
-  serviceApp?: ServiceApp;
-  serviceActingAs?: { userId: string; scopes: string[] };
-  oxyAuthRefusal?: OxyAuthRefusal;
-}
-
-interface AuthRes {
-  status(code: number): AuthRes;
-  json(body: unknown): unknown;
-}
-
-type AuthNext = (err?: unknown) => void;
-
-interface SocketLike {
-  handshake?: { auth?: { token?: string } };
-  data?: Record<string, unknown>;
-  user?: { id: string; userId: string; sessionId?: string | null };
-}
-
-interface OxyAuthInstance {
-  verifyServiceActingAs(appId: string, userId: string): Promise<ServiceActingAsVerification | null>;
-  getServiceToken(apiKey?: string, apiSecret?: string): Promise<string>;
-  validateSession(
-    sessionId: string,
-    options?: { deviceFingerprint?: string; useHeaderValidation?: boolean },
-  ): Promise<{
-    valid: boolean;
-    user?: User;
-    [key: string]: unknown;
-  } | null>;
-  handleError(error: unknown): Error;
-}