@oxy.so/core 7.18.0 → 7.19.0

package/dist/esm/server/namespaces.js

@@ -6,12 +6,13 @@ import { bindExternalMcpMediaLane, } from './externalMediaRequester.js';
  * `oxy.assets`.
  */
 import { agentAvailabilitySchema, capabilityTicketRequestSchema, foregroundExecutionAuthorizationInputSchema, firstPartyExecutionAuthorizationInputSchema, firstPartyTaskInputSchema, accountAccessVerdictSchema, } from '@oxy.so/contracts';
+import { sendWithCallOptions } from '../client/callOptions.js';
 import { bindRequesterLane } from './requesterContext.js';
 import { AssetsApi } from '../api/assets.js';
 import { runLargeUpload, } from './largeUpload.js';
 import { ASSET_JOB_POLL_INITIAL_MS, isPendingImport, nextPollInterval, sleep, waitForImport, } from './assetJobs.js';
 import { NotificationsApi } from '../api/notifications.js';
-import { OxyApiError } from '../OxyServices.errors.js';
+import { OxyApiError, retryAfterSecondsOf } from '../OxyServices.errors.js';
 import { LinkedAccountsApi } from '../api/linkedAccounts.js';
 import { AgencyApi, } from '../api/agency.js';
 import { ReputationApi } from '../api/reputation.js';
@@ -30,6 +31,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 = new Set([
+    '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. */
@@ -58,14 +67,6 @@ const SERVICE_RECONCILE_RATE_LIMIT_MAX_WAIT_MS = 60000;
 const SHA256_HEX_PATTERN = /^[a-f0-9]{64}$/;
 /** A header value fetch accepts on every runtime: printable ASCII only. */
 const HEADER_SAFE_PATTERN = /^[\x20-\x7e]*$/;
-/** The `RequestOptions` half of {@link ServiceCallOptions}, only the fields that were set. */
-function serviceCallRequestOptions(options) {
-    return {
-        ...(options.signal ? { signal: options.signal } : {}),
-        ...(options.timeout !== undefined ? { timeout: options.timeout } : {}),
-        ...(options.retry !== undefined ? { retry: options.retry } : {}),
-    };
-}
 /** The headers both streamed service uploads share. */
 function uploadHeaders(mime, description) {
     return {
@@ -181,6 +182,80 @@ export class ServerAssetsApi extends AssetsApi {
              */
             reconcile: (entityType, items, options = {}) => 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.
+         */
+        this.mediaCache = {
+            upload: (bytes, mime, options = {}) => lane(this.ctx).request('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) => {
+                await lane(this.ctx).request('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}.
+         */
+        this.federatedMedia = {
+            upload: async (ownerUserId, bytes, mime, options = {}) => {
+                const res = await lane(this.ctx).request('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) => {
+                const results = [];
+                for (const part of chunk(uniqueIds(fileIds), SERVICE_FEDERATED_DELETE_CHUNK_SIZE)) {
+                    const res = await lane(this.ctx).request('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)
@@ -326,7 +401,7 @@ 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(method, '/assets/service/references', { references: chunk }, { ...serviceCallRequestOptions(options), cache: false });
+            const res = await sendWithCallOptions({ cache: false }, options, (requestOptions) => lane(this.ctx).request(method, '/assets/service/references', { references: chunk }, requestOptions));
             results.push(...res.results);
         }
         return results;
@@ -1027,26 +1102,10 @@ async function waitingOutRateLimits(send) {
 }
 /** How long to wait after a refusal: what Oxy said, else the doubling fallback; capped. */
 function rateLimitWaitMs(error, refusals) {
-    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) {
-    if (!error || typeof error !== 'object')
-        return undefined;
-    const candidates = [
-        error.details,
-        error.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, path, sessionId) {
     const deadline = Date.now() + SERVICE_RECONCILE_COMMIT_WAIT_MS;
     let interval = ASSET_JOB_POLL_INITIAL_MS;

package/dist/esm/server/requesterClient.js

@@ -12,8 +12,6 @@ export class OxyRequesterClient extends OxyServices {
         return this.requesterLane.request(method, url, data, options);
     }
     get assets() {
-        if (!this.requesterAssets)
-            this.requesterAssets = new ServerAssetsApi(this.context);
-        return this.requesterAssets;
+        return this.namespace('assets', (context) => new ServerAssetsApi(context));
     }
 }

package/dist/esm/server/safeFetch.js

@@ -129,6 +129,28 @@ const BLOCKED_IPV6_CIDRS = [
     ['2001:db8::', 32], // documentation
     ['64:ff9b::', 96], // NAT64 (maps to IPv4 — IPv4 denylist still applies after unwrap)
 ];
+/**
+ * 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();
+/** `rawUrl`'s normalized form, or `null` when it is not a URL. */
+function normalizedUrl(rawUrl) {
+    try {
+        return new URL(rawUrl).href;
+    }
+    catch {
+        return null;
+    }
+}
+/** A successful check of `href`, registered as one this module issued. */
+function issueCheck(href, ip, family) {
+    const check = { 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.
@@ -210,7 +232,7 @@ export async function assertSafePublicUrl(rawUrl, options = {}) {
         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`
     // returned 0 (not a canonical IP literal), yet the host is made entirely of
@@ -251,11 +273,7 @@ export async function assertSafePublicUrl(rawUrl, options = {}) {
     }
     // 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. */
 const FIRST_PARTY_HOST_HINT = 'first-party Oxy host: inside the VPC it resolves to a private address, which safeFetch refuses by design; call it through OxyServer (its namespaces, serviceRequest, or createServiceClient().fetch), not safeFetch';
@@ -345,7 +363,13 @@ function fetchOnce(options, isHttps, headersTimeoutMs, body) {
  * @throws {UpstreamError} on redirect-loop / malformed-redirect / timeout.
  */
 export async function safeFetch(rawUrl, options = {}) {
-    const { method = 'GET', headers: callerHeaders, body, maxRedirects = MAX_REDIRECTS, redirect = 'follow', headersTimeoutMs = UPSTREAM_HEADERS_TIMEOUT_MS, signal, } = options;
+    const { method = 'GET', headers: callerHeaders, body, maxRedirects = MAX_REDIRECTS, 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 = {};
     if (callerHeaders) {
@@ -362,11 +386,18 @@ export async function safeFetch(rawUrl, options = {}) {
         if (signal?.aborted) {
             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)

package/dist/types/HttpService.d.ts

@@ -169,6 +169,8 @@ type EnvelopeGuard<T> = T extends object ? 'data' extends DeclaredKeys<T> ? [Ext
  * to carry the check to its own callers).
  */
 export type ResponsePayload<T> = T & EnvelopeGuard<T>;
+/** @internal Shared with `client/callOptions.ts`; see the note above `isAbortLike`. */
+export declare function linkAbort(parent: AbortSignal, child: AbortController): () => void;
 /**
  * Unified HTTP Service
  *

package/dist/types/OxyServices.d.ts

@@ -25,6 +25,7 @@ import { ContentClaimsApi } from './api/contentClaims';
 import { HttpService, type RequestOptions, type ResponsePayload } from './HttpService';
 import type { OxyConfig as OxyConfigBase } from './models/interfaces';
 import type { HttpMethod, OxyContext } from './client/context';
+import { type CallOptions } from './client/callOptions';
 import { SessionApi } from './api/session';
 import { AuthApi } from './api/auth';
 import { UsersApi } from './api/users';
@@ -69,6 +70,16 @@ export interface LinkedHttpClient {
 export declare const OXY_CLOUD_URL = "https://cloud.oxy.so";
 /** Default Oxy API URL. */
 export declare const OXY_API_URL = "https://api.oxy.so";
+/**
+ * The namespaces a call scope ({@link OxyServices.withCallOptions}) carries:
+ * every one but `session`, which is the client's auth state rather than a call.
+ */
+export type OxyCallScopeNamespace = 'auth' | 'users' | 'follows' | 'privacy' | 'notifications' | 'assets' | 'identity' | 'safety' | 'contentClaims' | 'organizations' | 'accounts' | 'apps' | 'linkedAccounts' | 'agency' | 'store' | 'billing' | 'reputation' | 'civic' | 'nodes' | 'devices' | 'topics' | 'appData' | 'console' | 'contacts';
+/**
+ * The namespaces of a client — an `OxyServer`'s server namespaces included —
+ * whose every request carries one set of {@link CallOptions}.
+ */
+export type OxyCallScope<T extends OxyServices = OxyServices> = Pick<T, OxyCallScopeNamespace>;
 export declare class OxyServices {
     /** The transport. Every namespace call goes through it. */
     readonly http: HttpService;
@@ -119,31 +130,33 @@ export declare class OxyServices {
     createLinkedClient(config: OxyConfig): LinkedHttpClient;
     /** Release this client: its cache stops being swept and its session ends. */
     dispose(): void;
-    private _session?;
-    private _auth?;
-    private _users?;
-    private _follows?;
-    private _privacy?;
-    private _notifications?;
-    private _assets?;
-    private _identity?;
-    private _accounts?;
-    private _organizations?;
-    private _safety?;
-    private _apps?;
-    private _linkedAccounts?;
-    private _agency?;
-    private _store?;
-    private _billing?;
-    private _reputation?;
-    private _civic?;
-    private _nodes?;
-    private _devices?;
-    private _topics?;
-    private _appData?;
-    private _contacts?;
-    private _console?;
-    private _contentClaims?;
+    /** Each namespace, created on first access and kept for the client's life. */
+    private readonly namespaceInstances;
+    /** The namespace `name`, created with this client's context on first access. */
+    protected namespace<T>(name: string, create: (context: OxyContext) => T): T;
+    /**
+     * This client's namespaces with per-call transport options: every request
+     * made through them carries `options`, on top of what each method sets.
+     *
+     * ```ts
+     * // One slow write, one tight read — one client.
+     * await oxy.withCallOptions({ timeout: 60_000 }).assets.setVisibility(id, 'public');
+     * const page = await oxy.withCallOptions({ deadline: 2_500 }).users.byUsername(name);
+     * // A server's own namespaces too:
+     * await server.withCallOptions({ retry: false }).assets.references.add(refs);
+     * ```
+     *
+     * - `timeout` / `deadline` replace the method's own and the client's.
+     * - `retry: false` sends each request once; `retry: true` never re-enables
+     *   a request the method sends once on purpose.
+     * - `signal` aborts the call; a method's own signal still applies too.
+     *
+     * The scope is a view, not a client: it shares this client's session,
+     * cache, credentials and service lane, holds no resource and needs no
+     * disposal. A namespace one call makes into another (`privacy` reading
+     * `users.me()`) keeps the options. `session` is not part of it.
+     */
+    withCallOptions(options: CallOptions): OxyCallScope<this>;
     /** This client's auth state (token, user id) and its server session. */
     get session(): SessionApi;
     /** Signing in, signing up, and the account's credentials. */

package/dist/types/OxyServices.errors.d.ts

@@ -142,6 +142,12 @@ export declare class OxyApiError extends Error {
         cause?: unknown;
     });
 }
+/**
+ * How long Oxy asked the caller to wait before trying again, in seconds — the
+ * `Retry-After` of a 429 (`details.retryAfterSeconds` of its body) — or
+ * `undefined` when the error is no such refusal or names no wait.
+ */
+export declare function retryAfterSecondsOf(error: unknown): number | undefined;
 /**
  * Normalise anything a request rejected with into an `OxyApiError`. An error
  * that already is one (or a typed SDK error such as `OxyAuthenticationError`)

package/dist/types/client/callOptions.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Per-call transport options, for any namespace call.
+ *
+ * `oxy.withCallOptions({ timeout: 60_000 }).assets.setVisibility(id, 'public')`
+ * sends that one call with its own budget, without a second client and without
+ * every method growing an options parameter of its own. The scope is a view of
+ * the same client: same session, cache, service lane and namespaces' state.
+ */
+import { type RequestOptions } from '../HttpService';
+/**
+ * Transport options for the calls made through `withCallOptions`, overriding
+ * the client's `requestTimeout` / `enableRetry` for those calls only.
+ */
+export interface CallOptions {
+    /** Abort the call. Combined with any signal the method passes itself. */
+    signal?: AbortSignal;
+    /** Per-attempt timeout in ms. Replaces the method's own default. */
+    timeout?: number;
+    /**
+     * Wall-clock budget in ms for the whole call, retries and backoff included
+     * (`RequestOptions.deadline`) — "never more than 2.5 s" in one number.
+     */
+    deadline?: number;
+    /**
+     * `false` sends each request once; a transient failure is the caller's to
+     * retry (an outbox). `true` allows the transport's retries where the client
+     * turned them off — but never on a request the method sends once on purpose
+     * (a non-idempotent write whose lost answer would duplicate it).
+     */
+    retry?: boolean;
+}
+/** Throws for a budget the transport cannot honour (0, negative, NaN, Infinity). */
+export declare function assertCallOptions(options: CallOptions): void;
+/**
+ * The request options a method chose, with the scope's applied on top. The
+ * signal is NOT merged here: two signals need a linked controller that lives
+ * exactly as long as the request ({@link sendWithCallOptions}).
+ */
+export declare function applyCallOptions<T extends RequestOptions>(method: T | undefined, scope: CallOptions): T;
+/**
+ * Send one request with the scope applied: `send` receives the merged
+ * options, with a signal that aborts when either the method's or the scope's
+ * does. The link between them is released when the request settles.
+ */
+export declare function sendWithCallOptions<T, O extends RequestOptions>(method: O | undefined, scope: CallOptions, send: (options: O) => Promise<T>): Promise<T>;

package/dist/types/index.d.ts

@@ -21,8 +21,9 @@
  */
 import './crypto/polyfill';
 export { OxyServices, OXY_API_URL, OXY_CLOUD_URL } from './OxyServices';
-export type { OxyConfig, LinkedHttpClient } from './OxyServices';
-export { OxyApiError, OxyAuthenticationError, OxyAuthenticationTimeoutError, AssetUrlResolutionError, ServiceAssetMetadataError, } from './OxyServices.errors';
+export type { OxyConfig, LinkedHttpClient, OxyCallScope, OxyCallScopeNamespace, } from './OxyServices';
+export type { CallOptions } from './client/callOptions';
+export { OxyApiError, OxyAuthenticationError, OxyAuthenticationTimeoutError, AssetUrlResolutionError, ServiceAssetMetadataError, retryAfterSecondsOf, } from './OxyServices.errors';
 export type { HttpMethod } from './client/context';
 export type { RequestOptions, ResponsePayload, ResponseRequest, ResponseTransport, AuthenticatedResponseRequest, AuthRefreshReason, AuthRefreshHandler, CredentialGeneration, } from './HttpService';
 export { sameHolderIdentity } from './api/holderEvidence';
@@ -75,7 +76,7 @@ export { SessionSyncRequiredError, AuthenticationFailedError, ensureValidToken,
 export type { HandleApiErrorOptions } from './utils/authHelpers';
 export { mergeSessions, normalizeAndSortSessions, sessionsArraysEqual, } from './utils/sessionUtils';
 export type { ClientSession, StorageKeys, MinimalUserData, SessionLoginResponse, } from './models/session';
-export type { PrivacySettings, NotificationPreferences, UserPreferences, User, LoginResponse, Notification, NotificationActor, NotificationPage, Wallet, Transaction, BlockedUser, RestrictedUser, TransferFundsRequest, PurchaseRequest, WithdrawalRequest, TransactionResponse, PaginationInfo, SearchProfilesResponse, ApiError, PaymentMethod, PaymentRequest, PaymentResponse, AnalyticsData, FollowerDetails, ContentViewer, FileMetadata, FileUploadResponse, FileListResponse, FileUpdateRequest, FileDeleteResponse, RNFileDescriptor, AssetUploadInput, FileVisibility, AssetLink, AssetMetadata, AssetVariant, Asset, AssetInitRequest, AssetInitResponse, AssetCompleteRequest, AssetLinkRequest, AssetUnlinkRequest, AssetUrlResponse, BatchFileAccessEntry, BatchFileAccessResponse, AssetDeleteSummary, AssetUpdateVisibilityRequest, AssetUpdateVisibilityResponse, ServiceAssetMetadata, AssetLiveStatus, AssetStatus, ServiceAssetMetadataBySha, ApplicationFile, ApplicationFileUpload, ApplicationFilePage, ServiceFileReference, ServiceFileReferenceResult, ServiceReferenceInventoryItem, ServiceReferenceReconcileResult, ServiceUserMediaFile, FileImportOutcome, FileImportSource, FileImportOptions, ApplicationFileImport, ApplicationFileImportBatchResult, ApplicationFileAdoption, ServiceUserMediaImport, AudioRenditionOptions, PendingFileImport, FileImportState, FileApplicationAccess, FileApplicationAccessRevocation, PlaySession, PlaySessionState, PlaySessionOptions, PlaySessionRendition, RecordingTarget, RecordingTargetOptions, RecordingTargetCredentials, CreatedRecordingTarget, AccountStorageCategoryUsage, AccountStorageUsageResponse, SecurityEventType, SecurityEventSeverity, SecurityActivity, SecurityActivityResponse, AssetUploadProgress, DeviceLinkedSession, DeviceLinkedSessionsResponse, DeviceLinkedSessionLogoutResponse, UpdateDeviceNameResponse, } from './models/interfaces';
+export type { PrivacySettings, NotificationPreferences, UserPreferences, User, LoginResponse, Notification, NotificationActor, NotificationPage, Wallet, Transaction, BlockedUser, RestrictedUser, TransferFundsRequest, PurchaseRequest, WithdrawalRequest, TransactionResponse, PaginationInfo, SearchProfilesResponse, ApiError, PaymentMethod, PaymentRequest, PaymentResponse, AnalyticsData, FollowerDetails, ContentViewer, FileMetadata, FileUploadResponse, FileListResponse, FileUpdateRequest, FileDeleteResponse, RNFileDescriptor, AssetUploadInput, FileVisibility, AssetLink, AssetMetadata, AssetVariant, Asset, AssetInitRequest, AssetInitResponse, AssetCompleteRequest, AssetLinkRequest, AssetUnlinkRequest, AssetUrlResponse, BatchFileAccessEntry, BatchFileAccessResponse, AssetDeleteSummary, AssetUpdateVisibilityRequest, AssetUpdateVisibilityResponse, ServiceAssetMetadata, AssetLiveStatus, AssetStatus, ServiceAssetMetadataBySha, ApplicationFile, ApplicationFileUpload, ApplicationFilePage, ServiceFileReference, ServiceFileReferenceResult, ServiceReferenceInventoryItem, ServiceReferenceReconcileResult, ServiceUserMediaFile, ServiceMediaCacheUpload, ServiceFederatedMediaUpload, ServiceFederatedMediaDeleteResult, ServiceFederatedMediaDeletion, FileImportOutcome, FileImportSource, FileImportOptions, ApplicationFileImport, ApplicationFileImportBatchResult, ApplicationFileAdoption, ServiceUserMediaImport, AudioRenditionOptions, PendingFileImport, FileImportState, FileApplicationAccess, FileApplicationAccessRevocation, PlaySession, PlaySessionState, PlaySessionOptions, PlaySessionRendition, RecordingTarget, RecordingTargetOptions, RecordingTargetCredentials, CreatedRecordingTarget, AccountStorageCategoryUsage, AccountStorageUsageResponse, SecurityEventType, SecurityEventSeverity, SecurityActivity, SecurityActivityResponse, AssetUploadProgress, DeviceLinkedSession, DeviceLinkedSessionsResponse, DeviceLinkedSessionLogoutResponse, UpdateDeviceNameResponse, } from './models/interfaces';
 export { SECURITY_EVENT_SEVERITY_MAP } from './models/interfaces';
 export { TopicType, TopicSource } from './models/Topic';
 export type { TopicData, TopicTranslation, TopicListResult } from './models/Topic';

package/dist/types/models/interfaces.d.ts

@@ -967,6 +967,29 @@ export interface ServiceUserMediaFile {
     mime: string;
     visibility: FileVisibility;
 }
+/** `POST /assets/service/cache`: the file now in the federation media cache. */
+export interface ServiceMediaCacheUpload {
+    file: {
+        id: string;
+    };
+}
+/** `POST /assets/service/federation`: durable federated media, owned by the federated user. */
+export interface ServiceFederatedMediaUpload {
+    file: ServiceUserMediaFile;
+    /** The owner already held these bytes from this application: the existing file, maybe shared. */
+    deduplicated: boolean;
+}
+/**
+ * Oxy's answer for one id of `assets.federatedMedia.delete`: `deleted` (this
+ * call removed it), `not_found` (nothing to delete), `in_use` (kept: another
+ * account holds the same bytes) or `forbidden` (not federated media this
+ * application uploaded; left untouched).
+ */
+export type ServiceFederatedMediaDeleteResult = 'deleted' | 'not_found' | 'in_use' | 'forbidden';
+export interface ServiceFederatedMediaDeletion {
+    id: string;
+    result: ServiceFederatedMediaDeleteResult;
+}
 /**
  * How Oxy renders an AUDIO file it stores (ADR 0043 stage 4c). Every audio
  * file gets an audio-only HLS ladder (AAC 64k/128k/256k, a rung above the

package/dist/types/server/OxyServer.d.ts

@@ -206,15 +206,6 @@ export declare class OxyServer extends OxyServices {
     private introspectResource;
     /** An isolated Oxy client carrying the original session, task or operation proof. */
     withRequester(proof: RequesterProof): OxyRequesterClient;
-    private _serverAccounts?;
-    private _serverAssets?;
-    private _serverNotifications?;
-    private _serverLinkedAccounts?;
-    private _serverAgency?;
-    private _serverApps?;
-    private _serverReputation?;
-    private _serverSafety?;
-    private _serverSession?;
     /** The account graph, plus the service-only `accessFor` membership verdict. */
     get accounts(): ServerAccountsApi;
     /** Files, plus the service-only metadata and linked-URL lookups. */

package/dist/types/server/namespaces.d.ts

@@ -6,8 +6,9 @@ import { type ExternalMcpDocumentProof, type ExternalMcpMediaProof } from './ext
  * `oxy.assets`.
  */
 import { type AgentAvailability, type FirstPartyTaskInput, type FirstPartyExecutionAuthorizationInput, type ForegroundExecutionAuthorizationInput, type ActorRef, type AppCapabilityCatalog, type AutonomyLevel, type CapabilityTicketClaims, type CapabilityTicketRequest, type GrantLimit, type PolicyDecision, type ResourceRef, type CreateOxyNotificationRequest, type AwardReputationInput, type ReputationTransaction, type ServiceLinkedAccountListResponse, type AccountAccessVerdict } from '@oxy.so/contracts';
+import { type CallOptions } from '../client/callOptions';
 import type { OxyContext } from '../client/context';
-import type { ApplicationFile, ApplicationFileAdoption, AssetLiveStatus, ApplicationFileImport, ApplicationFileImportBatchResult, ApplicationFilePage, ApplicationFileUpload, AudioRenditionOptions, CreatedRecordingTarget, FileImportOptions, FileImportState, FileVisibility, Notification, PlaySession, PlaySessionState, PlaySessionOptions, RecordingTarget, RecordingTargetOptions, ServiceAssetMetadata, ServiceAssetMetadataBySha, ServiceFileReference, ServiceFileReferenceResult, ServiceLinkedDownloadUrl, ServiceReferenceInventoryItem, ServiceReferenceReconcileResult, ServiceUserMediaFile, ServiceUserMediaImport } from '../models/interfaces';
+import type { ApplicationFile, ApplicationFileAdoption, AssetLiveStatus, ApplicationFileImport, ApplicationFileImportBatchResult, ApplicationFilePage, ApplicationFileUpload, AudioRenditionOptions, CreatedRecordingTarget, FileImportOptions, FileImportState, FileVisibility, Notification, PlaySession, PlaySessionState, PlaySessionOptions, RecordingTarget, RecordingTargetOptions, ServiceAssetMetadata, ServiceAssetMetadataBySha, ServiceFileReference, ServiceFileReferenceResult, ServiceLinkedDownloadUrl, ServiceReferenceInventoryItem, ServiceReferenceReconcileResult, ServiceUserMediaFile, ServiceUserMediaImport, ServiceMediaCacheUpload, ServiceFederatedMediaUpload, ServiceFederatedMediaDeletion } from '../models/interfaces';
 import { type RequesterProof } from './requesterContext';
 import { AssetsApi } from '../api/assets';
 import { type LargeServiceUploadOptions, type LargeServiceUploadResult, type LargeUploadSource } from './largeUpload';
@@ -21,20 +22,13 @@ import { type AliaMachineCredentialIntrospection } from './aliaMachineCredential
 import { type BatchLookup } from '../utils/batchLookup';
 /** 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;
-}
+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
@@ -103,6 +97,49 @@ export declare class ServerAssetsApi extends AssetsApi {
             dryRun?: boolean;
         }) => Promise<ServiceReferenceReconcileResult>;
     };
+    /**
+     * 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>;
+        delete: (fileId: string) => Promise<void>;
+    };
+    /**
+     * 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: (ownerUserId: string, bytes: ServiceUploadBody, mime: string, options?: ServiceUploadDescription) => Promise<ServiceFederatedMediaUpload>;
+        delete: (fileIds: string[]) => Promise<ServiceFederatedMediaDeletion[]>;
+    };
     /**
      * 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)

package/dist/types/server/requesterClient.d.ts

@@ -6,7 +6,6 @@ import { type RequesterProof } from './requesterContext';
 /** Oxy namespaces bound to one verified requester, without sharing mutable auth state. */
 export declare class OxyRequesterClient extends OxyServices {
     private readonly requesterLane;
-    private requesterAssets?;
     constructor(baseURL: string, cloudURL: string, original: ServiceLane, proof: RequesterProof);
     request<T>(method: HttpMethod, url: string, data?: unknown, options?: RequestOptions): Promise<ResponsePayload<T>>;
     get assets(): ServerAssetsApi;

package/dist/types/server/safeFetch.d.ts

@@ -150,6 +150,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;
 }
 /**
  * The validated response returned by {@link safeFetch}: the first non-redirect

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oxy.so/core",
-  "version": "7.18.0",
+  "version": "7.19.0",
   "description": "OxyHQ SDK Foundation — API client, authentication, cryptographic identity, and shared utilities",
   "main": "dist/cjs/index.js",
   "module": "dist/esm/index.js",

package/src/HttpService.ts

@@ -514,7 +514,8 @@ function isAbortLike(error: unknown): boolean {
   );
 }
 
-function linkAbort(parent: AbortSignal, child: AbortController): () => void {
+/** @internal Shared with `client/callOptions.ts`; see the note above `isAbortLike`. */
+export function linkAbort(parent: AbortSignal, child: AbortController): () => void {
   if (parent.aborted) {
     child.abort((parent as AbortSignal & { reason?: unknown }).reason);
     return () => {