@oxy.so/core 1.12.1 → 1.16.0

package/src/mixins/OxyServices.utility.ts

@@ -57,6 +57,73 @@ export interface ServiceActingAsVerification {
   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.
  *
@@ -334,6 +401,147 @@ export function OxyServicesUtilityMixin<T extends typeof OxyServicesBase>(Base:
       }
     }
 
+    /**
+     * 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
      *

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

@@ -0,0 +1,158 @@
+import { generateKeyPairSync, sign as signBytes, type KeyObject } from 'node:crypto';
+import { OxyServices } from '../../OxyServices';
+import { OXY_ACCOUNT_DELETED_EVENT_URI, OxyAccountEventError } from '../OxyServices.utility';
+
+const b64url = (value: string | Uint8Array): string => Buffer.from(value).toString('base64url');
+
+function sign(
+  privateKey: KeyObject,
+  header: Record<string, unknown>,
+  payload: Record<string, unknown>,
+): string {
+  const signingInput = `${b64url(JSON.stringify(header))}.${b64url(JSON.stringify(payload))}`;
+  return `${signingInput}.${b64url(signBytes(null, Buffer.from(signingInput), privateKey))}`;
+}
+
+const KID = 'oxy-service-test';
+
+function eventToken(
+  privateKey: KeyObject,
+  overrides: { header?: Record<string, unknown>; payload?: Record<string, unknown>; event?: Record<string, unknown> } = {},
+): string {
+  return sign(
+    privateKey,
+    { alg: 'EdDSA', typ: 'secevent+jwt', kid: KID, ...overrides.header },
+    {
+      iss: 'oxy-auth',
+      aud: 'app-mention',
+      iat: 1_790_000_000,
+      jti: '019a0000-0000-7000-8000-000000000001',
+      events: {
+        [OXY_ACCOUNT_DELETED_EVENT_URI]: {
+          userId: 'user-deleted',
+          username: 'qatest0925',
+          occurredAt: '2026-09-26T09:14:00.000Z',
+          retained: false,
+          ...overrides.event,
+        },
+      },
+      ...overrides.payload,
+    },
+  );
+}
+
+describe('verifyAccountEvent', () => {
+  const oxyKey = generateKeyPairSync('ed25519');
+  const strangerKey = generateKeyPairSync('ed25519');
+  const jwk = { ...oxyKey.publicKey.export({ format: 'jwk' }), use: 'sig', alg: 'EdDSA', kid: KID };
+
+  let fetchSpy: jest.SpyInstance;
+  beforeEach(() => {
+    fetchSpy = jest.spyOn(globalThis, 'fetch').mockImplementation(async () => new Response(
+      JSON.stringify({ keys: [jwk] }),
+      { status: 200, headers: { 'content-type': 'application/json' } },
+    ));
+  });
+  afterEach(() => jest.restoreAllMocks());
+
+  const client = () => new OxyServices({ baseURL: 'https://api.oxy.test' });
+
+  it('returns the event from a genuine Oxy-signed token, verified against the public JWKS', async () => {
+    const event = await client().verifyAccountEvent(eventToken(oxyKey.privateKey), { audience: 'app-mention' });
+
+    expect(event).toEqual({
+      eventId: '019a0000-0000-7000-8000-000000000001',
+      type: 'account.deleted',
+      userId: 'user-deleted',
+      username: 'qatest0925',
+      occurredAt: '2026-09-26T09:14:00.000Z',
+      retained: false,
+      applicationId: 'app-mention',
+      issuedAt: 1_790_000_000,
+    });
+    expect(fetchSpy).toHaveBeenCalledWith(
+      'https://api.oxy.test/.well-known/jwks.json',
+      expect.objectContaining({ method: 'GET', redirect: 'error' }),
+    );
+  });
+
+  it('reads a token without `username` (issued before the field existed) as username null', async () => {
+    const token = eventToken(oxyKey.privateKey, { event: { username: undefined } });
+    const event = await client().verifyAccountEvent(token, { audience: 'app-mention' });
+    expect(event.username).toBeNull();
+  });
+
+  it('carries `retained` through for an archived account', async () => {
+    const token = eventToken(oxyKey.privateKey, { event: { retained: true } });
+    await expect(client().verifyAccountEvent(token, { audience: 'app-mention' }))
+      .resolves.toMatchObject({ retained: true });
+  });
+
+  it('defaults the audience to the appId of the configured service credential', async () => {
+    const oxy = client();
+    const serviceToken = `${b64url(JSON.stringify({ alg: 'EdDSA' }))}.${b64url(JSON.stringify({ appId: 'app-mention' }))}.sig`;
+    jest.spyOn(oxy, 'getServiceToken').mockResolvedValue(serviceToken);
+
+    await expect(oxy.verifyAccountEvent(eventToken(oxyKey.privateKey))).resolves.toMatchObject({
+      applicationId: 'app-mention',
+    });
+    await expect(oxy.verifyAccountEvent(eventToken(oxyKey.privateKey, { payload: { aud: 'app-other' } })))
+      .rejects.toThrow('addressed to another application');
+  });
+
+  const refusals: Array<[string, () => string, string]> = [
+    ['a token signed by a key Oxy did not publish', () => eventToken(strangerKey.privateKey), 'signature is invalid'],
+    ['a service token (typ JWT) replayed as an event', () => eventToken(oxyKey.privateKey, { header: { typ: 'JWT' } }), 'header is not supported'],
+    ['a token for another application', () => eventToken(oxyKey.privateKey, { payload: { aud: 'app-other' } }), 'addressed to another application'],
+    ['a token from another issuer', () => eventToken(oxyKey.privateKey, { payload: { iss: 'someone-else' } }), 'issuer is not Oxy'],
+    ['a token without an event id', () => eventToken(oxyKey.privateKey, { payload: { jti: undefined } }), 'no event id'],
+    ['a token with an unknown event', () => eventToken(oxyKey.privateKey, { payload: { events: { 'https://oxy.so/events/other': {} } } }), 'unknown event'],
+    ['a token naming no account', () => eventToken(oxyKey.privateKey, { event: { userId: '' } }), 'names no account'],
+    ['a token whose username is not a string', () => eventToken(oxyKey.privateKey, { event: { username: 42 } }), 'username is malformed'],
+    ['a token with an unknown key id', () => eventToken(oxyKey.privateKey, { header: { kid: 'rotated-away' } }), 'unknown'],
+  ];
+
+  it.each(refusals)('refuses %s', async (_label, build, message) => {
+    const attempt = client().verifyAccountEvent(build(), { audience: 'app-mention' });
+    await expect(attempt).rejects.toBeInstanceOf(OxyAccountEventError);
+    await expect(client().verifyAccountEvent(build(), { audience: 'app-mention' })).rejects.toThrow(message);
+  });
+
+  it('refuses a tampered payload', async () => {
+    const [header, , signature] = eventToken(oxyKey.privateKey).split('.');
+    const forged = b64url(JSON.stringify({
+      iss: 'oxy-auth',
+      aud: 'app-mention',
+      iat: 1,
+      jti: 'x',
+      events: { [OXY_ACCOUNT_DELETED_EVENT_URI]: { userId: 'someone-else', occurredAt: '2026-09-26T00:00:00Z' } },
+    }));
+    await expect(client().verifyAccountEvent(`${header}.${forged}.${signature}`, { audience: 'app-mention' }))
+      .rejects.toThrow('signature is invalid');
+  });
+
+  it('refuses garbage without fetching keys', async () => {
+    await expect(client().verifyAccountEvent('not-a-token', { audience: 'app-mention' }))
+      .rejects.toThrow('not a compact JWS');
+    expect(fetchSpy).not.toHaveBeenCalled();
+  });
+});
+
+describe('listAccountEvents', () => {
+  afterEach(() => jest.restoreAllMocks());
+
+  it('reads the pull feed with the service token and passes the cursor', async () => {
+    const oxy = new OxyServices({ baseURL: 'https://api.oxy.test' });
+    jest.spyOn(oxy, 'getServiceToken').mockResolvedValue('service-token');
+    const page = { events: [], nextCursor: 'cursor-1' };
+    const request = jest.spyOn(oxy, 'makeRequest').mockResolvedValue(page as never);
+
+    await expect(oxy.listAccountEvents({ after: 'cursor-1', limit: 50 })).resolves.toEqual(page);
+    expect(request).toHaveBeenCalledWith(
+      'GET',
+      '/account-events',
+      { after: 'cursor-1', limit: '50' },
+      expect.objectContaining({ cache: false, headers: { Authorization: 'Bearer service-token' } }),
+    );
+  });
+});

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

@@ -218,6 +218,23 @@ describe('@oxy.so/core/server buildOxyPagesHeaders on a sensitive origin (ADR 00
     );
     expect(buildOxyPagesHeaders()).not.toContain('Cache-Control');
   });
+
+  it('serves the rest of the holder policy there, and only there (ADR 0028)', () => {
+    const sensitive = buildOxyPagesHeaders({ sensitive: true });
+    const normal = buildOxyPagesHeaders();
+
+    expect(sensitive).toContain("base-uri 'none'");
+    expect(sensitive).toContain("form-action 'none'");
+    expect(sensitive).toContain('Referrer-Policy: no-referrer');
+    expect(sensitive).toContain('Permissions-Policy: publickey-credentials-get=(self), publickey-credentials-create=(self)');
+    expect(sensitive).toContain('Cross-Origin-Resource-Policy: same-origin');
+    // The third-party OAuth popup reports back to its opener: COOP would sever it.
+    expect(sensitive).not.toContain('Cross-Origin-Opener-Policy');
+
+    expect(normal).toContain('Referrer-Policy: strict-origin-when-cross-origin');
+    expect(normal).not.toContain('Permissions-Policy');
+    expect(normal).not.toContain("base-uri 'none'");
+  });
 });
 
 describe('@oxy.so/core/server extractInlineScripts', () => {

package/src/server/securityHeaders.ts

@@ -371,6 +371,15 @@ export interface OxyPagesHeadersOptions {
    * 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.
+   *
+   * And, because this origin is the web identity carrier — where a person's
+   * self-custody root is created, opened, recovered and moved (ADR 0028) — the
+   * rest of the holder policy: no `<base>` and no form posts (`base-uri` /
+   * `form-action 'none'`), no Referer to anyone, passkeys for this origin only
+   * with every other powerful feature off (`Permissions-Policy`), and its
+   * responses readable by no other origin (`Cross-Origin-Resource-Policy`).
+   * Never `Cross-Origin-Opener-Policy`: the third-party OAuth popup reports
+   * its code to the app that opened it, and COOP severs `window.opener`.
    */
   sensitive?: boolean;
   /**
@@ -402,6 +411,21 @@ export interface OxyPagesHeadersOptions {
  * react-native-web's runtime stylesheet, and a style hash would silently switch
  * that off and render every Oxy web app unstyled.)
  */
+/** Passkeys for this origin itself; every other powerful feature off. */
+const SENSITIVE_PERMISSIONS_POLICY = [
+  'publickey-credentials-get=(self)',
+  'publickey-credentials-create=(self)',
+  'camera=()',
+  'microphone=()',
+  'geolocation=()',
+  'payment=()',
+  'usb=()',
+  'serial=()',
+  'hid=()',
+  'bluetooth=()',
+  'display-capture=()',
+].join(', ');
+
 export function buildOxyPagesHeaders(options: OxyPagesHeadersOptions = {}): string {
   const hashes = [
     ...new Set((options.html ?? []).flatMap(extractInlineScripts).map(inlineScriptCspHash)),
@@ -422,6 +446,8 @@ export function buildOxyPagesHeaders(options: OxyPagesHeadersOptions = {}): stri
     for (const name of ['script-src', 'connect-src']) {
       directives[name] = (directives[name] ?? []).filter((source) => !beacon.has(source));
     }
+    directives['base-uri'] = ["'none'"];
+    directives['form-action'] = ["'none'"];
   }
   const csp = formatOxyCspPolicy(directives);
   const lines = [
@@ -429,13 +455,15 @@ export function buildOxyPagesHeaders(options: OxyPagesHeadersOptions = {}): stri
     `  Content-Security-Policy: ${csp}`,
     '  X-Frame-Options: DENY',
     '  X-Content-Type-Options: nosniff',
-    '  Referrer-Policy: strict-origin-when-cross-origin',
+    `  Referrer-Policy: ${options.sensitive ? 'no-referrer' : 'strict-origin-when-cross-origin'}`,
   ];
   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(`  Permissions-Policy: ${SENSITIVE_PERMISSIONS_POLICY}`);
+    lines.push('  Cross-Origin-Resource-Policy: same-origin');
   }
   lines.push('');
   return lines.join('\n');