@oxy.so/core 7.18.0 → 7.19.1

package/src/server/OxyServer.ts

@@ -552,65 +552,47 @@ export class OxyServer extends OxyServices {
 
   // ── Server-side namespaces ───────────────────────────────────────────────
 
-  private _serverAccounts?: ServerAccountsApi;
-  private _serverAssets?: ServerAssetsApi;
-  private _serverNotifications?: ServerNotificationsApi;
-  private _serverLinkedAccounts?: ServerLinkedAccountsApi;
-  private _serverAgency?: ServerAgencyApi;
-  private _serverApps?: ServerAppsApi;
-  private _serverReputation?: ServerReputationApi;
-  private _serverSafety?: ServerSafetyApi;
-  private _serverSession?: ServerSessionApi;
-
   /** The account graph, plus the service-only `accessFor` membership verdict. */
   override get accounts(): ServerAccountsApi {
-    if (!this._serverAccounts) this._serverAccounts = new ServerAccountsApi(this.context);
-    return this._serverAccounts;
+    return this.namespace('accounts', (context) => new ServerAccountsApi(context));
   }
   /** Files, plus the service-only metadata and linked-URL lookups. */
   override get assets(): ServerAssetsApi {
-    if (!this._serverAssets) this._serverAssets = new ServerAssetsApi(this.context);
-    return this._serverAssets;
+    return this.namespace('assets', (context) => new ServerAssetsApi(context));
   }
   /** The inbox and push tokens, plus `create`. */
   override get notifications(): ServerNotificationsApi {
-    if (!this._serverNotifications)
-      this._serverNotifications = new ServerNotificationsApi(this.context);
-    return this._serverNotifications;
+    return this.namespace('notifications', (context) => new ServerNotificationsApi(context));
   }
   /** Linked external accounts, plus `forUser`. */
   override get linkedAccounts(): ServerLinkedAccountsApi {
-    if (!this._serverLinkedAccounts)
-      this._serverLinkedAccounts = new ServerLinkedAccountsApi(this.context);
-    return this._serverLinkedAccounts;
+    return this.namespace('linkedAccounts', (context) => new ServerLinkedAccountsApi(context));
   }
   /** Delegated capabilities, with the service-only authority calls. */
   override get agency(): ServerAgencyApi {
-    if (!this._serverAgency) this._serverAgency = new ServerAgencyApi(this.context);
-    return this._serverAgency;
+    return this.namespace('agency', (context) => new ServerAgencyApi(context));
   }
   /** Application management, plus the receiver-bound Alia machine-key lookup. */
   override get apps(): ServerAppsApi {
-    if (!this._serverApps) this._serverApps = new ServerAppsApi(this.context);
-    return this._serverApps;
+    return this.namespace('apps', (context) => new ServerAppsApi(context));
   }
   /** Reputation reads, plus `award`. */
   override get reputation(): ServerReputationApi {
-    if (!this._serverReputation) this._serverReputation = new ServerReputationApi(this.context);
-    return this._serverReputation;
+    return this.namespace('reputation', (context) => new ServerReputationApi(context));
   }
   /** Policy reads, plus the consumer-service decision lanes (ADR 0041). */
   override get safety(): ServerSafetyApi {
-    if (!this._serverSafety) this._serverSafety = new ServerSafetyApi(this.context);
-    return this._serverSafety;
+    return this.namespace('safety', (context) => new ServerSafetyApi(context));
   }
   /** Session state, plus validation through a reviewed supervised action. */
   override get session(): ServerSessionApi {
-    if (!this._serverSession)
-      this._serverSession = new ServerSessionApi(this.context, this.sessionValidationTtlMs, () =>
-        this.revocationFeedEpoch(),
-      );
-    return this._serverSession;
+    return this.namespace(
+      'session',
+      (context) =>
+        new ServerSessionApi(context, this.sessionValidationTtlMs, () =>
+          this.revocationFeedEpoch(),
+        ),
+    );
   }
 
   /** Close the revocation feed along with the HTTP client. */

package/src/server/appPermissions.ts

@@ -2,10 +2,13 @@
  * Application roles, from the application's side: which of THIS application's
  * declared permissions does the person behind a request hold?
  *
- * Oxy decides who holds an app's operator powers (`docs/auth/application-roles.md`).
- * An app declares its keys (`payments.operate`, …) in the Console, its owners
- * grant them to people, and its backend asks — so no app keeps a
- * `*_OPERATOR_OXY_USER_IDS` allow-list in its environment.
+ * Oxy decides who holds an app's operator powers (`docs/auth/application-roles.md`),
+ * and the backend asks — so no app keeps a `*_OPERATOR_OXY_USER_IDS` allow-list
+ * in its environment. One of Oxy's own applications declares its keys
+ * (`payments.operate`, …) in Oxy's first-party registry, each held by roles of
+ * the owning organization (ADR 0056); a third-party app declares them in the
+ * Console and its owners grant them to people. The answer has the same shape
+ * either way.
  *
  * ```ts
  * const oxy = new OxyServer({ baseURL: 'https://api.oxy.so', applicationId: process.env.OXY_APPLICATION_ID });

package/src/server/namespaces.ts

@@ -35,6 +35,7 @@ import {
   type AccountAccessVerdict,
 } from '@oxy.so/contracts';
 import type { RequestOptions } from '../HttpService';
+import { type CallOptions, sendWithCallOptions } from '../client/callOptions';
 import type { OxyContext, ServiceLane } from '../client/context';
 import type {
   ApplicationFile,
@@ -65,6 +66,10 @@ import type {
   ServiceReferenceReconcileResult,
   ServiceUserMediaFile,
   ServiceUserMediaImport,
+  ServiceMediaCacheUpload,
+  ServiceFederatedMediaUpload,
+  ServiceFederatedMediaDeletion,
+  ServiceFederatedMediaDeleteResult,
 } from '../models/interfaces';
 import { bindRequesterLane, type RequesterProof } from './requesterContext';
 import { AssetsApi } from '../api/assets';
@@ -82,7 +87,7 @@ import {
   waitForImport,
 } from './assetJobs';
 import { NotificationsApi } from '../api/notifications';
-import { OxyApiError } from '../OxyServices.errors';
+import { OxyApiError, retryAfterSecondsOf } from '../OxyServices.errors';
 import { LinkedAccountsApi } from '../api/linkedAccounts';
 import {
   AgencyApi,
@@ -109,6 +114,14 @@ const SERVICE_ASSET_METADATA_BY_SHA_CHUNK_SIZE = 100;
 const SERVICE_LINKED_DOWNLOAD_URL_CHUNK_SIZE = 25;
 /** Server-side cap of `POST`/`DELETE /assets/service/references`. */
 const SERVICE_REFERENCES_CHUNK_SIZE = 100;
+/** Server-side cap of `POST /assets/service/federation/delete`. */
+const SERVICE_FEDERATED_DELETE_CHUNK_SIZE = 20;
+const FEDERATED_DELETE_RESULTS: ReadonlySet<unknown> = new Set<ServiceFederatedMediaDeleteResult>([
+  'deleted',
+  'not_found',
+  'in_use',
+  'forbidden',
+]);
 /** Server-side cap of `POST /assets/service/app/import/batch`. */
 const SERVICE_IMPORT_BATCH_SIZE = 50;
 /** An import fetches a remote source (up to 60 s server-side): a longer per-attempt timeout. */
@@ -141,30 +154,14 @@ const HEADER_SAFE_PATTERN = /^[\x20-\x7e]*$/;
 /** The bytes of a streamed service upload: sent as the whole request body. */
 export type ServiceUploadBody = Uint8Array | ArrayBuffer | Blob;
 
-/** What `uploadAppFile` and `uploadUserMedia` may say about the bytes besides their type. */
 /**
- * Per-call transport options for a service call, overriding the server's
- * `requestTimeout` / `enableRetry` for that one call — so one `OxyServer` can
- * make a short, single-shot write and a patient read side by side.
+ * Per-call transport options for a service call — the {@link CallOptions}
+ * `withCallOptions` takes, accepted directly by the methods an outbox calls
+ * (`references.add` / `remove`).
  */
-export interface ServiceCallOptions {
-  /** Abort the call. */
-  signal?: AbortSignal;
-  /** Per-attempt timeout in ms. */
-  timeout?: number;
-  /** `false` sends the call once; a transient failure is the caller's to retry (an outbox). */
-  retry?: boolean;
-}
-
-/** The `RequestOptions` half of {@link ServiceCallOptions}, only the fields that were set. */
-function serviceCallRequestOptions(options: ServiceCallOptions): RequestOptions {
-  return {
-    ...(options.signal ? { signal: options.signal } : {}),
-    ...(options.timeout !== undefined ? { timeout: options.timeout } : {}),
-    ...(options.retry !== undefined ? { retry: options.retry } : {}),
-  };
-}
+export type ServiceCallOptions = CallOptions;
 
+/** What `uploadAppFile` and `uploadUserMedia` may say about the bytes besides their type. */
 export interface ServiceUploadDescription {
   /**
    * Stored as the file's original name. Sent as a header, so only printable
@@ -366,6 +363,107 @@ export class ServerAssetsApi extends AssetsApi {
       this.reconcileReferences(entityType, items, options),
   };
 
+  /**
+   * The federation media cache (`/assets/service/cache`): copies of remote
+   * media this application serves from Oxy's CDN instead of the remote host,
+   * in a reserved namespace that only holds what may be evicted. Every file
+   * is public by construction (`https://cloud.oxy.so/<id>`, `publicUrl`).
+   *
+   * - `upload` (`files:write`): the bytes as the whole body — a Blob from
+   *   `fs.openAsBlob(path)` streams a file from disk; image, video or audio
+   *   only (415), at most Oxy's cache size (413). Sent once.
+   * - `delete` (`federation:write`): evict one cache object. 404 when it is
+   *   gone, 403 for anything outside the cache namespace — a service token can
+   *   never delete media a person owns.
+   *
+   * A refusal for this application's media-write budget is a 429 whose
+   * `retryAfterSeconds` ({@link retryAfterSecondsOf}) says when to write again.
+   */
+  readonly mediaCache = {
+    upload: (
+      bytes: ServiceUploadBody,
+      mime: string,
+      options: ServiceUploadDescription = {},
+    ): Promise<ServiceMediaCacheUpload> =>
+      lane(this.ctx).request<ServiceMediaCacheUpload>('POST', '/assets/service/cache', bytes, {
+        headers: uploadHeaders(mime, options),
+        cache: false,
+        retry: false,
+        ...(options.signal ? { signal: options.signal } : {}),
+        ...(options.timeout ? { timeout: options.timeout } : {}),
+      }),
+    delete: async (fileId: string): Promise<void> => {
+      await lane(this.ctx).request<unknown>(
+        'DELETE',
+        `/assets/service/cache/${encodeURIComponent(fileId)}`,
+        undefined,
+        { cache: false },
+      );
+    },
+  };
+
+  /**
+   * Durable federated media (`/assets/service/federation`): a remote post's
+   * media re-hosted as a normal public file owned by the federated Oxy user
+   * it came from — outside the cache namespace, so a stored post may
+   * reference it for good.
+   *
+   * - `upload` (`files:write`): `ownerUserId` must be an existing federated
+   *   user (403). Idempotent per (owner, application, bytes): the existing
+   *   file with `deduplicated: true`, which other posts may share — check
+   *   your own references before deleting it. Bytes another owner or
+   *   application holds are a 409 `FEDERATED_MEDIA_OWNED_ELSEWHERE`. Sent once.
+   * - `delete` (`files:write` + `federation:write`): one answer per distinct
+   *   id, in order, sent 20 at a time — only federated media this application
+   *   uploaded is ever deleted (`forbidden` otherwise), and bytes another
+   *   account holds are kept (`in_use`). Every step is idempotent, so a failed
+   *   call is retried whole.
+   *
+   * Budget refusals are 429s, as for {@link mediaCache}.
+   */
+  readonly federatedMedia = {
+    upload: async (
+      ownerUserId: string,
+      bytes: ServiceUploadBody,
+      mime: string,
+      options: ServiceUploadDescription = {},
+    ): Promise<ServiceFederatedMediaUpload> => {
+      const res = await lane(this.ctx).request<ServiceFederatedMediaUpload>(
+        'POST',
+        '/assets/service/federation',
+        bytes,
+        {
+          headers: { ...uploadHeaders(mime, options), 'x-owner-user-id': ownerUserId },
+          cache: false,
+          retry: false,
+          ...(options.signal ? { signal: options.signal } : {}),
+          ...(options.timeout ? { timeout: options.timeout } : {}),
+        },
+      );
+      return { file: res.file, deduplicated: res.deduplicated === true };
+    },
+    delete: async (fileIds: string[]): Promise<ServiceFederatedMediaDeletion[]> => {
+      const results: ServiceFederatedMediaDeletion[] = [];
+      for (const part of chunk(uniqueIds(fileIds), SERVICE_FEDERATED_DELETE_CHUNK_SIZE)) {
+        const res = await lane(this.ctx).request<{ results: ServiceFederatedMediaDeletion[] }>(
+          'POST',
+          '/assets/service/federation/delete',
+          { ids: part },
+          { cache: false },
+        );
+        const asked = new Set(part);
+        for (const entry of Array.isArray(res?.results) ? res.results : []) {
+          // An id not asked, or a result this build does not know, is no
+          // answer: the caller sees the id unanswered and retries it.
+          if (asked.has(entry?.id) && FEDERATED_DELETE_RESULTS.has(entry?.result)) {
+            results.push({ id: entry.id, result: entry.result });
+          }
+        }
+      }
+      return results;
+    },
+  };
+
   /**
    * Per-play, revocable streaming access (ADR 0043 stage 4c). A play session
    * is ONE file's HLS ladder (a video's, or an audio file's audio-only one)
@@ -553,11 +651,13 @@ export class ServerAssetsApi extends AssetsApi {
       const chunk = references
         .slice(start, start + SERVICE_REFERENCES_CHUNK_SIZE)
         .map(({ fileId, entityType, entityId }) => ({ fileId, entityType, entityId }));
-      const res = await lane(this.ctx).request<{ results: ServiceFileReferenceResult[] }>(
-        method,
-        '/assets/service/references',
-        { references: chunk },
-        { ...serviceCallRequestOptions(options), cache: false },
+      const res = await sendWithCallOptions({ cache: false }, options, (requestOptions) =>
+        lane(this.ctx).request<{ results: ServiceFileReferenceResult[] }>(
+          method,
+          '/assets/service/references',
+          { references: chunk },
+          requestOptions,
+        ),
       );
       results.push(...res.results);
     }
@@ -1666,27 +1766,12 @@ async function waitingOutRateLimits<T>(send: () => Promise<T>): Promise<T> {
 
 /** How long to wait after a refusal: what Oxy said, else the doubling fallback; capped. */
 function rateLimitWaitMs(error: unknown, refusals: number): number {
-  const said = retryAfterSeconds(error);
+  const said = retryAfterSecondsOf(error);
   const wait =
     said !== undefined ? said * 1000 : SERVICE_RECONCILE_RATE_LIMIT_FALLBACK_MS * 2 ** refusals;
   return Math.min(wait, SERVICE_RECONCILE_RATE_LIMIT_MAX_WAIT_MS);
 }
 
-/** `details.retryAfterSeconds` of a refusal (`RateLimitedError` on the server), if any. */
-function retryAfterSeconds(error: unknown): number | undefined {
-  if (!error || typeof error !== 'object') return undefined;
-  const candidates = [
-    (error as { details?: { retryAfterSeconds?: unknown } }).details,
-    (error as { response?: { data?: { details?: { retryAfterSeconds?: unknown } } } }).response
-      ?.data?.details,
-  ];
-  for (const details of candidates) {
-    const seconds = details?.retryAfterSeconds;
-    if (typeof seconds === 'number' && Number.isFinite(seconds) && seconds > 0) return seconds;
-  }
-  return undefined;
-}
-
 async function waitForCommit(
   service: ServiceLane,
   path: string,

package/src/server/requesterClient.ts

@@ -7,7 +7,6 @@ import { bindRequesterLane, type RequesterProof } from './requesterContext';
 /** Oxy namespaces bound to one verified requester, without sharing mutable auth state. */
 export class OxyRequesterClient extends OxyServices {
   private readonly requesterLane: ServiceLane;
-  private requesterAssets?: ServerAssetsApi;
   constructor(baseURL: string, cloudURL: string, original: ServiceLane, proof: RequesterProof) {
     super({ baseURL, cloudURL });
     this.requesterLane = bindRequesterLane(original, proof);
@@ -22,7 +21,6 @@ export class OxyRequesterClient extends OxyServices {
     return this.requesterLane.request(method, url, data, options);
   }
   override get assets(): ServerAssetsApi {
-    if (!this.requesterAssets) this.requesterAssets = new ServerAssetsApi(this.context);
-    return this.requesterAssets;
+    return this.namespace('assets', (context) => new ServerAssetsApi(context));
   }
 }

package/src/server/safeFetch.ts

@@ -163,6 +163,30 @@ export interface SsrfCheckFail {
 
 export type SsrfCheckResult = SsrfCheckOk | SsrfCheckFail;
 
+/**
+ * Every successful check {@link assertSafePublicUrl} returned, and the exact
+ * URL it checked. `safeFetch({ validated })` accepts only these, for that URL:
+ * a hand-built `{ ok: true, ip }`, or a check of another URL, never pins a
+ * connection.
+ */
+const issuedChecks = new WeakMap<SsrfCheckOk, string>();
+
+/** `rawUrl`'s normalized form, or `null` when it is not a URL. */
+function normalizedUrl(rawUrl: string): string | null {
+  try {
+    return new URL(rawUrl).href;
+  } catch {
+    return null;
+  }
+}
+
+/** A successful check of `href`, registered as one this module issued. */
+function issueCheck(href: string, ip: string, family: 4 | 6): SsrfCheckOk {
+  const check: SsrfCheckOk = { ok: true, ip, family };
+  issuedChecks.set(check, href);
+  return check;
+}
+
 /**
  * Return true if a literal IP address is private/loopback/link-local/reserved/
  * multicast/metadata and therefore must NOT be contacted.
@@ -256,7 +280,7 @@ export async function assertSafePublicUrl(
     if (isBlockedIp(literalHost)) {
       return { ok: false, reason: 'literal ip in blocked range' };
     }
-    return { ok: true, ip: literalHost, family: literalFamily === 4 ? 4 : 6 };
+    return issueCheck(parsed.href, literalHost, literalFamily === 4 ? 4 : 6);
   }
 
   // Reject ambiguous numeric host forms BEFORE touching the resolver. `isIP`
@@ -301,11 +325,7 @@ export async function assertSafePublicUrl(
 
   // All records are public. Pin the connection to the first one.
   const chosen = records[0];
-  return {
-    ok: true,
-    ip: chosen.address,
-    family: chosen.family === 4 ? 4 : 6,
-  };
+  return issueCheck(parsed.href, chosen.address, chosen.family === 4 ? 4 : 6);
 }
 
 /** What a refusal of a first-party Oxy host adds to its reason. */
@@ -372,6 +392,22 @@ export interface SafeFetchOptions {
    * destroyed.
    */
   signal?: AbortSignal;
+  /**
+   * The check of this very URL the caller already made with
+   * {@link assertSafePublicUrl} (to refuse a URL before it reaches a cache, a
+   * queue or a database, say): the first hop connects to the address it
+   * validated instead of resolving the name again. Only a check
+   * `assertSafePublicUrl` returned for exactly `rawUrl` is accepted; anything
+   * else is a programming error and throws a `TypeError` before any request.
+   * Every redirect hop is still resolved and checked afresh.
+   */
+  validated?: SsrfCheckOk;
+  /**
+   * Refuse ({@link SsrfRejection}) any hop that is not https — the first, and
+   * every redirect — so no request of the chain is sent in the clear. Without
+   * it, http and https are both allowed on every hop.
+   */
+  requireHttps?: boolean;
 }
 
 /**
@@ -485,8 +521,19 @@ export async function safeFetch(
     redirect = 'follow',
     headersTimeoutMs = UPSTREAM_HEADERS_TIMEOUT_MS,
     signal,
+    validated,
+    requireHttps = false,
   } = options;
 
+  if (validated !== undefined) {
+    const checked = issuedChecks.get(validated);
+    if (checked === undefined || checked !== normalizedUrl(rawUrl)) {
+      throw new TypeError(
+        'safeFetch: `validated` must be the check assertSafePublicUrl returned for this exact URL',
+      );
+    }
+  }
+
   // Normalize a case-insensitive header map and ensure a User-Agent default.
   const baseHeaders: Record<string, string> = {};
   if (callerHeaders) {
@@ -506,11 +553,22 @@ export async function safeFetch(
       throw new UpstreamError('request aborted');
     }
 
-    // The lookup shares the headers deadline and the caller's signal.
-    const guard = await assertSafePublicUrl(currentUrl, {
-      lookupTimeoutMs: headersTimeoutMs,
-      signal,
-    });
+    if (requireHttps && !normalizedUrl(currentUrl)?.startsWith('https:')) {
+      throw new SsrfRejection(
+        hop === 0 ? 'https required' : 'https required: redirect to a non-https url',
+      );
+    }
+
+    // Hop 0 may reuse the caller's check of this exact URL; a redirect hop
+    // targets a new URL and is always checked here. The lookup shares the
+    // headers deadline and the caller's signal.
+    const guard =
+      hop === 0 && validated
+        ? validated
+        : await assertSafePublicUrl(currentUrl, {
+            lookupTimeoutMs: headersTimeoutMs,
+            signal,
+          });
     if (!guard.ok) {
       throw guard.incomplete
         ? new UpstreamError(guard.reason)