@oxy.so/core 7.18.0 → 7.19.0

package/dist/cjs/server/safeFetch.js

@@ -138,6 +138,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 node_url_1.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.
@@ -219,7 +241,7 @@ 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
@@ -260,11 +282,7 @@ 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';
@@ -356,7 +374,13 @@ function fetchOnce(options, isHttps, headersTimeoutMs, body) {
  * @throws {UpstreamError} on redirect-loop / malformed-redirect / timeout.
  */
 async function safeFetch(rawUrl, options = {}) {
-    const { method = 'GET', headers: callerHeaders, body, maxRedirects = exports.MAX_REDIRECTS, redirect = 'follow', headersTimeoutMs = exports.UPSTREAM_HEADERS_TIMEOUT_MS, signal, } = options;
+    const { method = 'GET', headers: callerHeaders, body, maxRedirects = exports.MAX_REDIRECTS, redirect = 'follow', headersTimeoutMs = exports.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) {
@@ -373,11 +397,18 @@ 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/esm/HttpService.js

@@ -298,7 +298,8 @@ function isAbortLike(error) {
         error !== null &&
         error.name === 'AbortError');
 }
-function linkAbort(parent, child) {
+/** @internal Shared with `client/callOptions.ts`; see the note above `isAbortLike`. */
+export function linkAbort(parent, child) {
     if (parent.aborted) {
         child.abort(parent.reason);
         return () => {

package/dist/esm/OxyServices.errors.js

@@ -136,6 +136,26 @@ export class OxyApiError extends Error {
         }
     }
 }
+/**
+ * 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 function retryAfterSecondsOf(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;
+}
 /**
  * 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/esm/OxyServices.js

@@ -25,6 +25,7 @@ import { ContentClaimsApi } from './api/contentClaims.js';
  */
 import { HttpService, } from './HttpService.js';
 import { toOxyApiError } from './OxyServices.errors.js';
+import { assertCallOptions, sendWithCallOptions } from './client/callOptions.js';
 import { SessionApi } from './api/session.js';
 import { AuthApi } from './api/auth.js';
 import { UsersApi } from './api/users.js';
@@ -64,6 +65,9 @@ export class OxyServices {
             deletePrefix: (prefix) => this.http.clearCacheByPrefix(prefix),
             stats: () => this.http.getCacheStats(),
         };
+        // ── Namespaces (created on first access) ─────────────────────────────────
+        /** Each namespace, created on first access and kept for the client's life. */
+        this.namespaceInstances = new Map();
         if (!config || typeof config !== 'object') {
             throw new Error('OxyConfig is required');
         }
@@ -166,150 +170,157 @@ export class OxyServices {
     dispose() {
         this.http.dispose();
     }
+    /** The namespace `name`, created with this client's context on first access. */
+    namespace(name, create) {
+        let instance = this.namespaceInstances.get(name);
+        if (instance === undefined) {
+            instance = create(this.context);
+            this.namespaceInstances.set(name, instance);
+        }
+        return instance;
+    }
+    /**
+     * 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) {
+        assertCallOptions(options);
+        const scope = { ...options };
+        const base = this.context;
+        const lane = base.service;
+        const view = Object.create(this);
+        const context = {
+            oxy: view,
+            http: base.http,
+            request: (method, url, data, requestOptions) => sendWithCallOptions(requestOptions, scope, (merged) => base.request(method, url, data, merged)),
+            service: lane && {
+                get available() {
+                    return lane.available;
+                },
+                request: (method, url, data, requestOptions) => sendWithCallOptions(requestOptions, scope, (merged) => lane.request(method, url, data, merged)),
+            },
+        };
+        // The view's own namespaces are built on the scoped context; everything
+        // else (http, cache, config, credentials) is this client's, by prototype.
+        Object.defineProperties(view, {
+            context: { value: context },
+            namespaceInstances: { value: new Map() },
+            session: { get: () => this.session },
+        });
+        return view;
+    }
     /** This client's auth state (token, user id) and its server session. */
     get session() {
-        if (!this._session)
-            this._session = new SessionApi(this.context);
-        return this._session;
+        return this.namespace('session', (context) => new SessionApi(context));
     }
     /** Signing in, signing up, and the account's credentials. */
     get auth() {
-        if (!this._auth)
-            this._auth = new AuthApi(this.context);
-        return this._auth;
+        return this.namespace('auth', (context) => new AuthApi(context));
     }
     /** People and their profiles. */
     get users() {
-        if (!this._users)
-            this._users = new UsersApi(this.context);
-        return this._users;
+        return this.namespace('users', (context) => new UsersApi(context));
     }
     /** The follow graph: people and every other followable target. */
     get follows() {
-        if (!this._follows)
-            this._follows = new FollowsApi(this.context);
-        return this._follows;
+        return this.namespace('follows', (context) => new FollowsApi(context));
     }
     /** Privacy settings, blocks and restrictions. */
     get privacy() {
-        if (!this._privacy)
-            this._privacy = new PrivacyApi(this.context);
-        return this._privacy;
+        return this.namespace('privacy', (context) => new PrivacyApi(context));
     }
     /** The in-app inbox and push tokens. */
     get notifications() {
-        if (!this._notifications)
-            this._notifications = new NotificationsApi(this.context);
-        return this._notifications;
+        return this.namespace('notifications', (context) => new NotificationsApi(context));
     }
     /** Files: upload, link, URLs, content. */
     get assets() {
-        if (!this._assets)
-            this._assets = new AssetsApi(this.context);
-        return this._assets;
+        return this.namespace('assets', (context) => new AssetsApi(context));
     }
     /** DID, keys, identity links, domains, backup and the signed export. */
     get identity() {
-        if (!this._identity)
-            this._identity = new IdentityApi(this.context);
-        return this._identity;
+        return this.namespace('identity', (context) => new IdentityApi(context));
     }
     /** The account graph: accounts and their members. */
     get safety() {
-        if (!this._safety)
-            this._safety = new SafetyApi(this.context);
-        return this._safety;
+        return this.namespace('safety', (context) => new SafetyApi(context));
     }
     /** Content claims: an owner's counter-notice to a takedown (ADR 0043 D10). */
     get contentClaims() {
-        if (!this._contentClaims)
-            this._contentClaims = new ContentClaimsApi(this.context);
-        return this._contentClaims;
+        return this.namespace('contentClaims', (context) => new ContentClaimsApi(context));
     }
     get organizations() {
-        if (!this._organizations)
-            this._organizations = new OrganizationsApi(this.context);
-        return this._organizations;
+        return this.namespace('organizations', (context) => new OrganizationsApi(context));
     }
     get accounts() {
-        if (!this._accounts)
-            this._accounts = new AccountsApi(this.context);
-        return this._accounts;
+        return this.namespace('accounts', (context) => new AccountsApi(context));
     }
     /** Applications an account owns, and the ones this user granted access. */
     get apps() {
-        if (!this._apps)
-            this._apps = new AppsApi(this.context);
-        return this._apps;
+        return this.namespace('apps', (context) => new AppsApi(context));
     }
     /** External accounts (Mastodon, Bluesky) linked by OAuth. */
     get linkedAccounts() {
-        if (!this._linkedAccounts)
-            this._linkedAccounts = new LinkedAccountsApi(this.context);
-        return this._linkedAccounts;
+        return this.namespace('linkedAccounts', (context) => new LinkedAccountsApi(context));
     }
     /** Delegated capabilities for agents. */
     get agency() {
-        if (!this._agency)
-            this._agency = new AgencyApi(this.context);
-        return this._agency;
+        return this.namespace('agency', (context) => new AgencyApi(context));
     }
     /** The app store: storefront, reviews, and a publisher's listing. */
     get store() {
-        if (!this._store)
-            this._store = new StoreApi(this.context);
-        return this._store;
+        return this.namespace('store', (context) => new StoreApi(context));
     }
     /** Subscription, wallet and payments. */
     get billing() {
-        if (!this._billing)
-            this._billing = new BillingApi(this.context);
-        return this._billing;
+        return this.namespace('billing', (context) => new BillingApi(context));
     }
     /** Oxy Trust reputation (read-only for people; apps award it). */
     get reputation() {
-        if (!this._reputation)
-            this._reputation = new ReputationApi(this.context);
-        return this._reputation;
+        return this.namespace('reputation', (context) => new ReputationApi(context));
     }
     /** Oxy ID: cards, attestations, vouching, personhood, credentials. */
     get civic() {
-        if (!this._civic)
-            this._civic = new CivicApi(this.context);
-        return this._civic;
+        return this.namespace('civic', (context) => new CivicApi(context));
     }
     /** The user's personal data node. */
     get nodes() {
-        if (!this._nodes)
-            this._nodes = new NodesApi(this.context);
-        return this._nodes;
+        return this.namespace('nodes', (context) => new NodesApi(context));
     }
     /** This user's devices, their sessions, and device sign-in. */
     get devices() {
-        if (!this._devices)
-            this._devices = new DevicesApi(this.context);
-        return this._devices;
+        return this.namespace('devices', (context) => new DevicesApi(context));
     }
     get topics() {
-        if (!this._topics)
-            this._topics = new TopicsApi(this.context);
-        return this._topics;
+        return this.namespace('topics', (context) => new TopicsApi(context));
     }
     /** Per-app key/value data stored on the user's account. */
     get appData() {
-        if (!this._appData)
-            this._appData = new AppDataApi(this.context);
-        return this._appData;
+        return this.namespace('appData', (context) => new AppDataApi(context));
     }
     /** Oxy Console: first-run onboarding (terms and use cases) for the signed-in person. */
     get console() {
-        if (!this._console)
-            this._console = new ConsoleApi(this.context);
-        return this._console;
+        return this.namespace('console', (context) => new ConsoleApi(context));
     }
     get contacts() {
-        if (!this._contacts)
-            this._contacts = new ContactsApi(this.context);
-        return this._contacts;
+        return this.namespace('contacts', (context) => new ContactsApi(context));
     }
 }

package/dist/esm/client/callOptions.js

@@ -0,0 +1,61 @@
+/**
+ * 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 { linkAbort } from '../HttpService.js';
+/** Throws for a budget the transport cannot honour (0, negative, NaN, Infinity). */
+export function assertCallOptions(options) {
+    for (const key of ['timeout', 'deadline']) {
+        const value = options[key];
+        if (value !== undefined && (!Number.isFinite(value) || value <= 0)) {
+            throw new RangeError(`${key} must be a positive number of milliseconds`);
+        }
+    }
+}
+/**
+ * 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 function applyCallOptions(method, scope) {
+    const merged = { ...method };
+    if (scope.timeout !== undefined)
+        merged.timeout = scope.timeout;
+    if (scope.deadline !== undefined)
+        merged.deadline = scope.deadline;
+    if (scope.retry === false)
+        merged.retry = false;
+    else if (scope.retry === true && merged.retry === undefined)
+        merged.retry = true;
+    return merged;
+}
+/**
+ * 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 async function sendWithCallOptions(method, scope, send) {
+    const merged = applyCallOptions(method, scope);
+    const own = method?.signal;
+    if (!scope.signal || !own || own === scope.signal) {
+        const signal = scope.signal ?? own;
+        if (signal)
+            merged.signal = signal;
+        return send(merged);
+    }
+    const controller = new AbortController();
+    const unlinkOwn = linkAbort(own, controller);
+    const unlinkScope = linkAbort(scope.signal, controller);
+    merged.signal = controller.signal;
+    try {
+        return await send(merged);
+    }
+    finally {
+        unlinkOwn();
+        unlinkScope();
+    }
+}

package/dist/esm/index.js

@@ -29,7 +29,7 @@ import './crypto/polyfill.js';
 // API client
 // ---------------------------------------------------------------------------
 export { OxyServices, OXY_API_URL, OXY_CLOUD_URL } from './OxyServices.js';
-export { OxyApiError, OxyAuthenticationError, OxyAuthenticationTimeoutError, AssetUrlResolutionError, ServiceAssetMetadataError, } from './OxyServices.errors.js';
+export { OxyApiError, OxyAuthenticationError, OxyAuthenticationTimeoutError, AssetUrlResolutionError, ServiceAssetMetadataError, retryAfterSecondsOf, } from './OxyServices.errors.js';
 export { sameHolderIdentity } from './api/holderEvidence.js';
 export { ASSET_MULTIPART_UPLOAD_MAX_BYTES, assetUrlCacheTTL, MAX_UPLOAD_BYTES } from './api/assets.js';
 export { DirectUploadInterruptedError } from './api/directUpload.js';

package/dist/esm/server/OxyServer.js

@@ -321,59 +321,42 @@ export class OxyServer extends OxyServices {
             throw new Error('Requester context requires an authenticated service');
         return new OxyRequesterClient(this.baseURL, this.cloudURL, service, proof);
     }
+    // ── Server-side namespaces ───────────────────────────────────────────────
     /** The account graph, plus the service-only `accessFor` membership verdict. */
     get accounts() {
-        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. */
     get assets() {
-        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`. */
     get notifications() {
-        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`. */
     get linkedAccounts() {
-        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. */
     get agency() {
-        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. */
     get apps() {
-        if (!this._serverApps)
-            this._serverApps = new ServerAppsApi(this.context);
-        return this._serverApps;
+        return this.namespace('apps', (context) => new ServerAppsApi(context));
     }
     /** Reputation reads, plus `award`. */
     get reputation() {
-        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). */
     get safety() {
-        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. */
     get session() {
-        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. */
     dispose() {