@oxy.so/core 1.9.1 → 1.11.0

package/src/mixins/__tests__/linkedAccounts.test.ts

@@ -0,0 +1,109 @@
+/**
+ * Linked-accounts SDK surface: the paths, methods and bodies it sends, and the
+ * `{ data }` unwrapping. The flow itself is exercised in the API's route tests.
+ */
+
+import { OxyServices } from '../../OxyServices';
+
+function makeJwt(payload: Record<string, unknown>): string {
+  const b64url = (obj: Record<string, unknown>): string => Buffer.from(JSON.stringify(obj)).toString('base64url');
+  const fullPayload = { exp: Math.floor(Date.now() / 1000) + 3600, ...payload };
+  return `${b64url({ alg: 'none', typ: 'JWT' })}.${b64url(fullPayload)}.sig`;
+}
+
+function jsonResponse(data: unknown, status = 200): Response {
+  return new Response(status === 204 ? null : JSON.stringify({ data }), {
+    status,
+    headers: { 'content-type': 'application/json' },
+  });
+}
+
+const LINK = {
+  id: 'link-1',
+  network: 'activitypub' as const,
+  accountKey: 'nate@mastodon.social',
+  actorUri: 'https://mastodon.social/users/nate',
+  handle: '@nate@mastodon.social',
+  host: 'mastodon.social',
+  proofMethod: 'oauth' as const,
+  verifiedAt: '2026-09-25T00:00:00.000Z',
+  createdAt: '2026-09-25T00:00:00.000Z',
+};
+
+describe('linked accounts', () => {
+  let originalFetch: typeof globalThis.fetch;
+  let fetchMock: jest.Mock<Promise<Response>, [RequestInfo | URL, RequestInit?]>;
+  let oxy: OxyServices;
+
+  beforeEach(() => {
+    originalFetch = globalThis.fetch;
+    fetchMock = jest.fn();
+    globalThis.fetch = fetchMock as unknown as typeof globalThis.fetch;
+    oxy = new OxyServices({ baseURL: 'http://test.invalid' });
+    oxy.httpService.setTokens(makeJwt({ userId: 'me' }));
+  });
+
+  afterEach(() => {
+    globalThis.fetch = originalFetch;
+    jest.clearAllMocks();
+  });
+
+  it('starts a link with POST /linked-accounts/:network/start and returns the authorize URL', async () => {
+    fetchMock.mockResolvedValueOnce(
+      jsonResponse({ authorizeUrl: 'https://mastodon.social/oauth/authorize?x=1', expiresAt: '2026-09-25T00:10:00.000Z' }),
+    );
+    const started = await oxy.startLinkedAccount('activitypub', {
+      instance: 'mastodon.social',
+      clientId: 'oxy_dk_move',
+      returnTo: 'https://move.oxy.so/linked',
+    });
+    expect(started.authorizeUrl).toBe('https://mastodon.social/oauth/authorize?x=1');
+    const [url, init] = fetchMock.mock.calls[0];
+    expect(String(url)).toBe('http://test.invalid/linked-accounts/activitypub/start');
+    expect(init?.method).toBe('POST');
+    expect(JSON.parse(String(init?.body))).toEqual({
+      instance: 'mastodon.social',
+      clientId: 'oxy_dk_move',
+      returnTo: 'https://move.oxy.so/linked',
+    });
+  });
+
+  it('completes a link with POST /linked-accounts/complete and returns the link', async () => {
+    fetchMock.mockImplementation(async (url) =>
+      String(url).endsWith('/linked-accounts/complete') ? jsonResponse({ linkedAccount: LINK }) : jsonResponse({ csrfToken: 't'.repeat(32) }),
+    );
+    expect(await oxy.completeLinkedAccount('one-time-code')).toEqual(LINK);
+    const completion = fetchMock.mock.calls.find(([url]) => String(url).endsWith('/linked-accounts/complete'));
+    expect(completion?.[1]?.method).toBe('POST');
+    expect(JSON.parse(String(completion?.[1]?.body))).toEqual({ code: 'one-time-code' });
+  });
+
+  it('lists the live links, unwrapping the envelope, without caching', async () => {
+    fetchMock.mockImplementation(async () => jsonResponse({ linkedAccounts: [LINK] }));
+    expect(await oxy.listLinkedAccounts()).toEqual([LINK]);
+    await oxy.listLinkedAccounts();
+    expect(fetchMock).toHaveBeenCalledTimes(2);
+    expect(String(fetchMock.mock.calls[0][0])).toBe('http://test.invalid/linked-accounts');
+  });
+
+  it('revokes with DELETE /linked-accounts/:id', async () => {
+    // A state-changing request may first fetch a CSRF token; answer anything.
+    fetchMock.mockImplementation(async (_url, init) =>
+      init?.method === 'DELETE' ? new Response(null, { status: 204 }) : jsonResponse({ csrfToken: 't'.repeat(32) }),
+    );
+    await oxy.revokeLinkedAccount('link-1');
+    const deletion = fetchMock.mock.calls.find(([, init]) => init?.method === 'DELETE');
+    expect(String(deletion?.[0])).toBe('http://test.invalid/linked-accounts/link-1');
+  });
+
+  it('reads a user\'s links on the service lane with a service token', async () => {
+    const service = new OxyServices({ baseURL: 'http://test.invalid' });
+    jest.spyOn(service, 'getServiceToken').mockResolvedValue('service-token');
+    fetchMock.mockResolvedValueOnce(jsonResponse({ userId: 'u1', linkedAccounts: [{ ...LINK, federatedUserId: null }] }));
+    const result = await service.getLinkedAccountsForUser('u1');
+    expect(result.linkedAccounts[0].federatedUserId).toBeNull();
+    const [url, init] = fetchMock.mock.calls[0];
+    expect(String(url)).toBe('http://test.invalid/linked-accounts/by-user/u1');
+    expect(new Headers(init?.headers).get('authorization')).toBe('Bearer service-token');
+  });
+});

package/src/mixins/__tests__/topics.test.ts

@@ -24,8 +24,7 @@ function rawResponse(body: unknown): Response {
 
 /**
  * A non-verified JWT whose payload decodes to the given claims. Puts the SDK in
- * an authenticated state so the `POST /topics/resolve` carries a bearer header
- * and skips the CSRF-token pre-fetch (which would otherwise consume a mock).
+ * an authenticated state so the `POST /topics/resolve` carries a bearer header.
  */
 function makeJwt(payload: Record<string, unknown>): string {
   const b64url = (obj: Record<string, unknown>): string =>
@@ -59,7 +58,7 @@ describe('topics mixin envelope unwrapping', () => {
     fetchMock = jest.fn();
     globalThis.fetch = fetchMock as unknown as typeof globalThis.fetch;
     oxy = new OxyServices({ baseURL: 'http://test.invalid', enableRetry: false });
-    // Authenticate so the resolve POST skips the CSRF pre-fetch. Harmless for GETs.
+    // Authenticate so the resolve POST carries a bearer. Harmless for GETs.
     oxy.httpService.setTokens(makeJwt({ userId: 'me' }));
   });
 

package/src/mixins/index.ts

@@ -35,6 +35,7 @@ import { OxyServicesNodesMixin } from './OxyServices.nodes';
 import { OxyServicesFollowGraphMixin } from './OxyServices.followGraph';
 import { OxyServicesInferenceMixin } from './OxyServices.inference';
 import { OxyServicesDeviceBootMixin } from './OxyServices.deviceBoot';
+import { OxyServicesLinkedAccountsMixin } from './OxyServices.linkedAccounts';
 
 /**
  * Instance shape of every mixin in the pipeline, intersected. The runtime
@@ -74,6 +75,7 @@ type AllMixinInstances =
   & InstanceType<ReturnType<typeof OxyServicesFollowGraphMixin<typeof OxyServicesBase>>>
   & InstanceType<ReturnType<typeof OxyServicesInferenceMixin<typeof OxyServicesBase>>>
   & InstanceType<ReturnType<typeof OxyServicesDeviceBootMixin<typeof OxyServicesBase>>>
+  & InstanceType<ReturnType<typeof OxyServicesLinkedAccountsMixin<typeof OxyServicesBase>>>
   & InstanceType<ReturnType<typeof OxyServicesUtilityMixin<typeof OxyServicesBase>>>;
 
 /**
@@ -165,6 +167,10 @@ const MIXIN_PIPELINE: MixinFunction[] = [
     // (`mintFromDeviceSecret` → `POST /session/device/token`).
     OxyServicesDeviceBootMixin,
 
+    // Linked external accounts (Mastodon-API, Bluesky) proven by OAuth; the
+    // service read uses the auth mixin's `makeServiceRequest`.
+    OxyServicesLinkedAccountsMixin,
+
     // Device-to-device identity transfer ("add a device"): E2E-encrypted key
     // clone over a short-lived relay (b3 Feature 2).
 

package/src/models/interfaces.ts

@@ -115,6 +115,13 @@ export interface User {
    * lists, profile search) — the two are separate fields on the User document.
    */
   description?: string;
+  /**
+   * ActivityPub actor URIs this account is also known as — its live,
+   * OAuth-proven linked Mastodon-API accounts. Emitted by
+   * `GET /profiles/username/:username`; a relying app passes it to the shared
+   * actor builder (`@oxy.so/federation`) so its actor publishes it.
+   */
+  alsoKnownAs?: string[];
   phone?: string;
   address?: string;
   /** Legacy free-text birthday, kept for backward compatibility. Prefer `dateOfBirth`. */
@@ -263,7 +270,22 @@ export interface LoginResponse {
 export interface Notification {
   id: string;
   message: string;
-  // Add other notification fields as needed
+  /** One of `OXY_NOTIFICATION_TYPES` (`@oxy.so/contracts`). */
+  type?: string;
+  /**
+   * `system` notifications only (with `message`): the text an Oxy service sent
+   * about the recipient's own account. Render these two instead of composing a
+   * sentence from actor + entity.
+   */
+  title?: string;
+  /** `system` notifications only: an optional deep link (https or the sending app's scheme). */
+  url?: string;
+  /**
+   * What `entityId` names: `post` | `reply` | `profile`, or `app` — an opaque id
+   * in the notifying application's namespace (`system` notifications only).
+   */
+  entityType?: string;
+  entityId?: string;
 }
 
 export interface Wallet {
@@ -666,6 +688,13 @@ export interface ServiceAssetMetadata {
    * play. Treat absence as "no adaptive stream, play the progressive original".
    */
   hlsReadyAt?: string;
+  /**
+   * The Oxy user who owns the file (`null` for a system-owned file such as the
+   * federated media cache). PRESENT ONLY for Oxy's own applications (service
+   * tokens with `tier: 'internal'`), so a first-party service can check that an
+   * asset a user attached is really that user's. Absent for every other caller.
+   */
+  ownerUserId?: string | null;
 }
 
 /**

package/src/server/__tests__/securityHeaders.test.ts

@@ -211,6 +211,13 @@ describe('@oxy.so/core/server buildOxyPagesHeaders on a sensitive origin (ADR 00
     expect(sensitive).toContain('https://api.oxy.so');
     expect(sensitive).toContain("frame-ancestors 'none'");
   });
+
+  it('sends no-transform so the edge never injects the beacon, and only there', () => {
+    expect(buildOxyPagesHeaders({ sensitive: true })).toContain(
+      'Cache-Control: public, max-age=0, must-revalidate, no-transform',
+    );
+    expect(buildOxyPagesHeaders()).not.toContain('Cache-Control');
+  });
 });
 
 describe('@oxy.so/core/server extractInlineScripts', () => {

package/src/server/cors.ts

@@ -40,7 +40,6 @@ const DEFAULT_ALLOWED_HEADERS = [
   'X-Requested-With',
   'X-Oxy-User-Id',
   'X-Oxy-Internal',
-  'X-CSRF-Token',
   'X-Oxy-Edge-Region',
   'X-Oxy-Activity-Id',
 ];

package/src/server/securityHeaders.ts

@@ -366,6 +366,11 @@ export interface OxyPagesHeadersOptions {
    * the app — is REMOVED from `script-src` and `connect-src`, so third-party
    * measurement cannot run there even when the zone has Web Analytics enabled.
    * A structural block in the policy the page is served with, not a build flag.
+   *
+   * It also sends `Cache-Control: no-transform`, which stops the edge from
+   * injecting the beacon at all — otherwise every page load logs a CSP
+   * violation for a script we never asked for. The rest of the value is Pages'
+   * own default, so caching is unchanged.
    */
   sensitive?: boolean;
   /**
@@ -429,6 +434,9 @@ export function buildOxyPagesHeaders(options: OxyPagesHeadersOptions = {}): stri
   if (options.hsts !== false) {
     lines.push('  Strict-Transport-Security: max-age=31536000; includeSubDomains; preload');
   }
+  if (options.sensitive) {
+    lines.push('  Cache-Control: public, max-age=0, must-revalidate, no-transform');
+  }
   lines.push('');
   return lines.join('\n');
 }

package/src/session/__tests__/refresh.identityPin.test.ts

@@ -82,7 +82,7 @@ function makeOxy(overrides: OxyOverrides = {}): { oxy: OxyServices; setTokens: j
       overrides.requestChallenge
       ?? (async () => ({ challenge: 'chal-1', expiresAt: '2030-01-01T00:00:00.000Z' })),
     verifyChallenge: overrides.verifyChallenge ?? (async () => IDENTITY_SESSION),
-    httpService: { runSingleFlightDeviceSecretMint: makeMintSingleFlight() },
+    httpService: { runSingleFlightDeviceSecretMint: makeMintSingleFlight(), getSessionEpoch: () => 0 },
   } as unknown as OxyServices;
   return { oxy, setTokens };
 }

package/src/session/__tests__/refresh.test.ts

@@ -59,8 +59,18 @@ interface RefreshMockOverrides {
 
 function makeOxy(
   overrides: RefreshMockOverrides = {},
-): { oxy: OxyServices; setTokens: jest.Mock; noteRefreshRateLimited: jest.Mock } {
+): {
+  oxy: OxyServices;
+  setTokens: jest.Mock;
+  noteRefreshRateLimited: jest.Mock;
+  /** `HttpService`'s session epoch; bump it to simulate a sign-out mid-refresh. */
+  epoch: { current: number };
+  /** `HttpService.hasSessionEnded()`: a sign-out with no token planted since. */
+  ended: { current: boolean };
+} {
   const setTokens = jest.fn();
+  const epoch = { current: 0 };
+  const ended = { current: false };
   const noteRefreshRateLimited = jest.fn();
   const oxy = {
     setTokens,
@@ -71,9 +81,11 @@ function makeOxy(
     httpService: {
       runSingleFlightDeviceSecretMint: makeMintSingleFlight(),
       noteRefreshRateLimited,
+      getSessionEpoch: () => epoch.current,
+      hasSessionEnded: () => ended.current,
     },
   } as unknown as OxyServices;
-  return { oxy, setTokens, noteRefreshRateLimited };
+  return { oxy, setTokens, noteRefreshRateLimited, epoch, ended };
 }
 
 describe('refreshPersistedSession — arm 1 (device-secret mint)', () => {
@@ -297,6 +309,107 @@ describe('refreshPersistedSession — arm 2 (native shared-key fallback)', () =>
   });
 });
 
+describe('refreshPersistedSession — a sign-out mid-refresh', () => {
+  it('arm 1: plants nothing and leaves a cleared store cleared', async () => {
+    const store = createMemoryAuthStateStore();
+    await store.save(STORED);
+    let respond!: () => void;
+    const { oxy, setTokens, epoch } = makeOxy({
+      mintFromDeviceSecret: () =>
+        new Promise((resolve) => {
+          respond = () => resolve(MINT);
+        }),
+    });
+
+    const pending = refreshPersistedSession({ oxy, store, allowSharedKeyFallback: true });
+    await new Promise((resolve) => setTimeout(resolve, 0));
+    // The sign-out: the credential is dropped and the session epoch moves.
+    await store.clear();
+    epoch.current += 1;
+    respond();
+
+    await expect(pending).resolves.toBeNull();
+    expect(setTokens).not.toHaveBeenCalled();
+    expect(await store.load()).toBeNull();
+  });
+
+  it('arm 1: still persists the rotated secret when the store kept the credential', async () => {
+    const store = createMemoryAuthStateStore();
+    await store.save(STORED);
+    let respond!: () => void;
+    const { oxy, setTokens, epoch } = makeOxy({
+      mintFromDeviceSecret: () =>
+        new Promise((resolve) => {
+          respond = () => resolve(MINT);
+        }),
+    });
+
+    const pending = refreshPersistedSession({ oxy, store, allowSharedKeyFallback: false });
+    await new Promise((resolve) => setTimeout(resolve, 0));
+    // A local teardown that keeps the store (so a reload can restore): the
+    // server rotated the secret, and the store must not be left holding the old one.
+    epoch.current += 1;
+    respond();
+
+    await expect(pending).resolves.toBeNull();
+    expect(setTokens).not.toHaveBeenCalled();
+    expect((await store.load())?.deviceSecret).toBe('ds-next-secret');
+  });
+
+  it('arm 2: the shared keychain does not sign the user back in', async () => {
+    const store = createMemoryAuthStateStore();
+    let respond!: () => void;
+    const signInWithSharedIdentity = jest.fn(
+      (_opts?: { plantTokens?: boolean }) =>
+        new Promise<SessionLoginResponse>((resolve) => {
+          respond = () =>
+            resolve({
+              sessionId: 'sess-shared',
+              deviceId: 'dev-1',
+              deviceSecret: 'ds-shared',
+              expiresAt: '2030-01-01T00:00:00.000Z',
+              user: { id: 'user-1', username: 'u', name: {}, avatar: undefined },
+              accessToken: 'access-shared',
+            });
+        }),
+    );
+    const { oxy, setTokens, epoch } = makeOxy({ signInWithSharedIdentity });
+
+    const pending = refreshPersistedSession({ oxy, store, allowSharedKeyFallback: true });
+    await new Promise((resolve) => setTimeout(resolve, 0));
+    epoch.current += 1;
+    respond();
+
+    await expect(pending).resolves.toBeNull();
+    expect(signInWithSharedIdentity).toHaveBeenCalledWith({ plantTokens: false });
+    expect(setTokens).not.toHaveBeenCalled();
+    expect(await store.load()).toBeNull();
+  });
+});
+
+describe('refreshPersistedSession — after a sign-out', () => {
+  it('does not re-sign-in with the shared keychain', async () => {
+    const store = createMemoryAuthStateStore();
+    const signInWithSharedIdentity = jest.fn(async () => null);
+    const { oxy, setTokens, ended } = makeOxy({ signInWithSharedIdentity });
+    ended.current = true;
+
+    await expect(refreshPersistedSession({ oxy, store, allowSharedKeyFallback: true })).resolves.toBeNull();
+    expect(signInWithSharedIdentity).not.toHaveBeenCalled();
+    expect(setTokens).not.toHaveBeenCalled();
+  });
+
+  it('still mints from a device credential the store holds (a sign-in made in another tab)', async () => {
+    const store = createMemoryAuthStateStore();
+    await store.save(STORED);
+    const { oxy, setTokens, ended } = makeOxy();
+    ended.current = true;
+
+    await expect(refreshPersistedSession({ oxy, store, allowSharedKeyFallback: true })).resolves.toBe('access-new');
+    expect(setTokens).toHaveBeenCalledWith('access-new');
+  });
+});
+
 describe('refreshPersistedSession — single-flight (no double-rotation)', () => {
   it('coalesces two concurrent mints into ONE server rotation; the store holds the final current secret', async () => {
     // The server rotates the secret on every mint. Two concurrent lanes must

package/src/session/refresh.ts

@@ -114,6 +114,11 @@ export interface RefreshDeps {
  *    The device secret is FINE — it is the identity binding that went stale, so
  *    the caller must re-establish from the local key, never drop the credential.
  *  - `transient` — network / 5xx; keep the secret, a later attempt can succeed.
+ *  - `session-ended` — the mint succeeded, but the local session was ended
+ *    (`HttpService.endSession`, i.e. a sign-out) while it was in flight. Nothing
+ *    is planted. The rotated secret is persisted only if the store still holds
+ *    the credential that was presented — a store the sign-out cleared stays
+ *    clear.
  *  - `persist-failed` — the mint succeeded but `nextDeviceSecret` could NOT be
  *    durably persisted. The token is deliberately NOT planted: advertising a
  *    healthy session on a secret that will not survive a reload is exactly the
@@ -126,6 +131,7 @@ export type DeviceSecretMintOutcome =
   | { status: 'no-session' }
   | { status: 'account-not-on-device' }
   | { status: 'transient' }
+  | { status: 'session-ended' }
   | { status: 'persist-failed' };
 
 /**
@@ -159,6 +165,7 @@ export async function refreshDeviceSecretArm(deps: {
   const { oxy, store } = deps;
   const pin = deps.pin ?? null;
   return oxy.httpService.runSingleFlightDeviceSecretMint(async () => {
+    const epoch = oxy.httpService.getSessionEpoch();
     const persisted = await store.load();
     if (!persisted?.deviceId || !persisted?.deviceSecret) {
       return { status: 'no-secret' };
@@ -222,12 +229,26 @@ export async function refreshDeviceSecretArm(deps: {
       expiresAt: mint.expiresAt,
       ...(bound ? { sessionId: bound.sessionId, userId: bound.accountId } : {}),
     };
+    if (oxy.httpService.getSessionEpoch() !== epoch) {
+      // Signed out while minting. The server has rotated the secret, so a store
+      // that still holds the presented one must learn the rotation (the
+      // token-null lane keeps the store so a reload can restore); a store the
+      // sign-out cleared must NOT be refilled. Either way, plant nothing.
+      const current = await store.load();
+      if (current?.deviceId === persisted.deviceId && current.deviceSecret === persisted.deviceSecret) {
+        await store.save(next);
+      }
+      return { status: 'session-ended' };
+    }
     // Persist nextDeviceSecret (read-back-verified) BEFORE planting the token.
     // A failed durable persist must NOT plant.
     const persistedOk = await store.save(next);
     if (!persistedOk) {
       return { status: 'persist-failed' };
     }
+    if (oxy.httpService.getSessionEpoch() !== epoch) {
+      return { status: 'session-ended' };
+    }
     oxy.setTokens(mint.accessToken);
     return {
       status: 'ok',
@@ -266,6 +287,7 @@ export async function refreshPersistedSession(deps: RefreshDeps): Promise<string
   const identity = deps.identity ?? null;
   // The shared keychain is never an identity-bound client's recovery path.
   const allowSharedKeyFallback = identity ? false : (deps.allowSharedKeyFallback ?? isNative());
+  const epoch = oxy.httpService.getSessionEpoch();
   // Resolved per call: a re-established identity session can move the pin, and a
   // replaced/removed local key clears it (in which case arm 1 must NOT mint —
   // an unpinned mint would adopt whatever account the device switched to).
@@ -278,6 +300,8 @@ export async function refreshPersistedSession(deps: RefreshDeps): Promise<string
   switch (arm1.status) {
     case 'ok':
       return arm1.token;
+    case 'session-ended':
+      return null;
     case 'transient':
       logger.debug(
         'Persisted deviceSecret mint failed (transient) — keeping store',
@@ -327,10 +351,18 @@ export async function refreshPersistedSession(deps: RefreshDeps): Promise<string
     return recoverIdentitySession(oxy, store, identity);
   }
 
-  if (allowSharedKeyFallback) {
+  // Never after a sign-out: the shared keychain holds an identity KEY, not a
+  // session, and using it here would sign the user straight back in.
+  if (allowSharedKeyFallback && !oxy.httpService.hasSessionEnded()) {
     try {
-      const session = await oxy.signInWithSharedIdentity();
+      // Planted here, not by the sign-in: a sign-out that lands while the
+      // challenge round-trips must win, or the shared keychain signs the user
+      // straight back in.
+      const session = await oxy.signInWithSharedIdentity({ plantTokens: false });
       if (session?.accessToken) {
+        if (oxy.httpService.getSessionEpoch() !== epoch) {
+          return null;
+        }
         // Repopulate the fast device-secret lane from the shared-key re-mint.
         if (session.deviceId && session.deviceSecret) {
           await store.save({
@@ -342,6 +374,10 @@ export async function refreshPersistedSession(deps: RefreshDeps): Promise<string
             expiresAt: session.expiresAt,
           });
         }
+        if (oxy.httpService.getSessionEpoch() !== epoch) {
+          return null;
+        }
+        oxy.setTokens(session.accessToken);
         return session.accessToken;
       }
     } catch (error) {

package/src/utils/errorUtils.ts

@@ -121,7 +121,7 @@ const nonEmptyString = (value: unknown): string | undefined =>
  * - `{ error: '<CODE>', error_description }` — RFC 6749 §5.2 / RFC 6750 §3, the
  *   OAuth token and userinfo endpoints. `error_description` is the human text
  *   and `error` is the machine code, so both survive.
- * - `{ message, code }` — e.g. the API's CSRF rejections.
+ * - `{ message, code }` — e.g. the API's middleware rejections.
  * - `{ error: '<human message>' }` — legacy hand-rolled routes. With no sibling
  *   `message`/`error_description` the string is the message, not a code: a bare
  *   `error` string is not machine-readable enough to promote to `code`.