@oxyhq/core 12.11.1 → 13.2.0

package/dist/types/index.d.ts

@@ -26,7 +26,7 @@ export { getCommonsApprovalBlockingReason, parseCommonsApprovalExpiresAt, } from
 export { selectCommonsDelivery, pushTargetsFromDelivery, commonsDeliveryPlatform } from './utils/commonsDelivery';
 export type { CommonsDeliveryFacts, CommonsDeliveryPlatform, CommonsDeliveryRoute, } from './utils/commonsDelivery';
 export type { ServiceTokenResponse } from './mixins/OxyServices.auth';
-export type { CommonsSignInHandle, CommonsSignInStatus, CommonsSignInPurpose, CommonsOAuthContext, CommonsApprovalInfo, CommonsApprovalSubjectAccount, CommonsSignInActionResult, CommonsDenyReason, CommonsOAuthFinalizeResult, CommonsDeliveryResult, } from './mixins/OxyServices.auth';
+export type { CommonsSignInHandle, CommonsSignInStatus, CommonsSignInPurpose, CommonsOAuthContext, CommonsApprovalInfo, CommonsApprovalSubjectAccount, CommonsSignInActionResult, CommonsOAuthFinalizeResult, CommonsDeliveryResult, } from './mixins/OxyServices.auth';
 export type { PushTokenPlatform, RegisterPushTokenInput, } from './mixins/OxyServices.notifications';
 export type { ServiceApp, ServiceActingAsVerification } from './mixins/OxyServices.utility';
 export type { ContactDiscoveryMatch, ContactDiscoveryResponse, } from './mixins/OxyServices.contacts';
@@ -80,8 +80,8 @@ export { HttpStatus, getErrorStatus, getErrorMessage, isAlreadyRegisteredError,
 export { DEFAULT_CIRCUIT_BREAKER_CONFIG, createCircuitBreakerState, calculateBackoffInterval, recordFailure, recordSuccess, shouldAllowRequest, delay, withRetry, } from './shared/utils/networkUtils';
 export type { CircuitBreakerState, CircuitBreakerConfig } from './shared/utils/networkUtils';
 export { translate } from './i18n';
-export { buildSearchParams, buildUrl, buildPaginationParams, safeJsonParse, } from './utils/apiUtils';
-export type { PaginationParams, ApiResponse, ErrorResponse, } from './utils/apiUtils';
+export { buildQueryParams, buildSearchParams, buildUrl, buildPaginationParams, safeJsonParse, } from './utils/apiUtils';
+export type { PaginationParams, FollowGraphParams, FollowGraphSort, ApiResponse, ErrorResponse, } from './utils/apiUtils';
 export { ErrorCodes, createApiError, handleHttpError, validateRequiredFields, } from './utils/errorUtils';
 export { retryAsync } from './utils/asyncUtils';
 export { EMAIL_REGEX, USERNAME_REGEX, PASSWORD_REGEX, isValidEmail, isValidUsername, isValidPassword, isValidDisplayName, DISPLAY_NAME_ALLOWED_SCRIPTS, DISPLAY_NAME_DISALLOWED_SOURCE, DISPLAY_NAME_ORPHANED_MARK_SOURCE, isRequiredString, isRequiredNumber, isRequiredBoolean, isValidArray, isValidObject, isValidUUID, isValidURL, isValidDate, isValidFileSize, isValidFileType, sanitizeString, sanitizeHTML, isValidObjectId, validateAndSanitizeUserInput, } from './utils/validationUtils';
@@ -96,11 +96,9 @@ export { CENTRAL_IDP_APEX } from './utils/authWebUrl';
 export { isOxyRpOrigin } from './utils/webauthnOrigin';
 export { runColdBoot } from './utils/coldBoot';
 export type { ColdBootStep, ColdBootStepResult, ColdBootSession, ColdBootSkip, ColdBootOutcome, RunColdBootOptions, } from './utils/coldBoot';
-export { buildOAuthAuthorizeUrl, computeCodeChallenge, generateOAuthState, generatePkcePair, DEFAULT_OAUTH_SCOPE, OXY_AUTHORIZE_URL, OXY_OAUTH_STATE_STORAGE_KEY, OXY_OAUTH_CODE_VERIFIER_STORAGE_KEY, OXY_OAUTH_REDIRECT_URI_STORAGE_KEY, OXY_SILENT_OAUTH_ATTEMPTED_KEY, OXY_CROSS_ORIGIN_RESTORE_ATTEMPTED_KEY, OXY_OAUTH_RETURN_PATH_STORAGE_KEY, normalizeOAuthRedirectUri, canonicalizeOAuthRedirectUri, persistOAuthHandshake, readOAuthHandshake, clearOAuthHandshake, persistOAuthReturnPath, consumeOAuthReturnPath, } from './utils/oauthPkce';
+export { buildOAuthAuthorizeUrl, computeCodeChallenge, generateOAuthState, generatePkcePair, DEFAULT_OAUTH_SCOPE, OXY_AUTHORIZE_URL, OXY_OAUTH_STATE_STORAGE_KEY, OXY_OAUTH_CODE_VERIFIER_STORAGE_KEY, OXY_OAUTH_REDIRECT_URI_STORAGE_KEY, OXY_OAUTH_RETURN_PATH_STORAGE_KEY, normalizeOAuthRedirectUri, canonicalizeOAuthRedirectUri, persistOAuthHandshake, readOAuthHandshake, clearOAuthHandshake, persistOAuthReturnPath, consumeOAuthReturnPath, } from './utils/oauthPkce';
 export type { PkcePair, BuildOAuthAuthorizeUrlParams } from './utils/oauthPkce';
-export { buildIdpHubOrigin, buildHubSyncUrl, isIdpHubOrigin, isLoopbackOrigin, isOfficialWebOrigin, isAllowedDeviceJoinOrigin, normalizeOfficialReturnOrigin, parseHubSyncReturnUrl, } from './utils/officialOrigins';
-export { syncHubAfterSignIn, redeemHubTicketOnHub, } from './session/hubSync';
-export type { SyncHubAfterSignInOptions } from './session/hubSync';
+export { isLoopbackOrigin, isOfficialWebOrigin, isAllowedDeviceJoinOrigin, } from './utils/officialOrigins';
 export { SessionClient } from './session/SessionClient';
 export type { TokenTransport, SessionClientHost, SessionClientOptions, DeviceCredential, SessionStateOrigin } from './session/SessionClient';
 export type { SocketIOFactory, MinimalSocket } from './session/socketLoader';

package/dist/types/mixins/OxyServices.auth.d.ts

@@ -4,7 +4,7 @@
  * Supports password-based login (email/username) and public key challenge-response.
  */
 import type { User } from '../models/interfaces';
-import type { LoginResult, LoginSessionResult } from '@oxyhq/contracts';
+import type { LoginResult, LoginSessionResult, CommonsDenyReason } from '@oxyhq/contracts';
 import type { SessionLoginResponse } from '../models/session';
 import type { OxyServicesBase } from '../OxyServices.base';
 import type { PublicApplication } from './OxyServices.connectedApps';
@@ -226,17 +226,6 @@ export interface CommonsApprovalInfo {
 export interface CommonsSignInActionResult {
     success: boolean;
 }
-/**
- * Why the approver denied a "Sign in with Oxy" request. A CLOSED set — the deny
- * endpoint is unauthenticated, so it accepts no free-form text:
- *
- *  - `'declined'` the approver rejected a request they recognised ("Not now").
- *  - `'not_me'`   the approver did not start the request ("This wasn't me").
- *                 The only value that records the denial as suspicious rather
- *                 than an ordinary cancel, so a UI may only offer it where the
- *                 user genuinely said so.
- */
-export type CommonsDenyReason = 'declined' | 'not_me';
 /**
  * Result of finalizing an approved, OAuth-bound "Sign in with Oxy" request.
  *

package/dist/types/mixins/OxyServices.deviceBoot.d.ts

@@ -13,7 +13,7 @@
  * the cold boot / re-mint handler own persistence and `setTokens`, so the same
  * primitive can be reused from either without double-planting.
  */
-import { type DeviceTokenMintResponse, type DeviceHubTicketIssueResponse, type DeviceHubTicketRedeemResponse } from '@oxyhq/contracts';
+import { type DeviceTokenMintResponse } from '@oxyhq/contracts';
 import type { OxyServicesBase } from '../OxyServices.base';
 /**
  * The server's `401 account_not_on_device` for a PINNED mint: the requested
@@ -71,10 +71,6 @@ export declare function OxyServicesDeviceBootMixin<T extends typeof OxyServicesB
         mintFromDeviceSecret(deviceId: string, deviceSecret: string, options?: {
             accountId?: string;
         }): Promise<DeviceTokenMintResponse>;
-        /** Mint a one-time hub sync ticket (bearer required). */
-        issueHubTicket(returnOrigin: string): Promise<DeviceHubTicketIssueResponse>;
-        /** Redeem a hub sync ticket for a fresh device secret (public). */
-        redeemHubTicket(ticket: string, returnOrigin: string): Promise<DeviceHubTicketRedeemResponse>;
         httpService: import("../HttpService").HttpService;
         cloudURL: string;
         config: import("../OxyServices.base").OxyConfig;

package/dist/types/mixins/OxyServices.user.d.ts

@@ -4,7 +4,7 @@
 import type { User, Notification, NotificationPreferences, UserPreferences, SearchProfilesResponse, PrivacySettings } from '../models/interfaces';
 import type { UserNameResponse, UserProfileUpdate, RecommendationRequest, RecommendationItem, ThemePreference } from '@oxyhq/contracts';
 import type { OxyServicesBase } from '../OxyServices.base';
-import { type PaginationParams } from '../utils/apiUtils';
+import { type PaginationParams, type FollowGraphParams } from '../utils/apiUtils';
 /**
  * Response of the single follow/unfollow toggle route
  * (`POST /users/:id/follow` and `DELETE /users/:id/follow`). The route reports a
@@ -329,6 +329,22 @@ export declare function OxyServicesUserMixin<T extends typeof OxyServicesBase>(B
         deleteAccount(confirmText: string): Promise<{
             message: string;
         }>;
+        /**
+         * Invalidate every cached read a follow/unfollow write invalidates.
+         *
+         * Shared by the four mutation entry points (`followUser`, `unfollowUser`,
+         * `followUsers`, `unfollowUsers`) so they can never drift on which caches a
+         * write busts.
+         *
+         * The follower/following/mutuals LISTS are cleared by PREFIX rather than by
+         * exact key. Those reads are paginated and ordered, so one logical list is
+         * spread across many content-addressed keys
+         * (`GET:/users/<id>/followers:{"limit":"20","offset":"40","sort":"oldest"}`);
+         * an exact-key clear would only bust whichever page/sort variant happened to
+         * be read last and would leave every other page stale. `clearCacheByPrefix`
+         * deletes all of them, and all identity-scoped variants of each.
+         */
+        invalidateFollowGraphCaches(targetUserIds: string[]): void;
         /**
          * Follow a user.
          *
@@ -386,17 +402,22 @@ export declare function OxyServicesUserMixin<T extends typeof OxyServicesBase>(B
          */
         getFollowStatuses(userIds: string[]): Promise<Record<string, boolean>>;
         /**
-         * Get user followers
+         * Get user followers.
+         *
+         * `sort` orders the underlying follow edges — `recent` (newest first, the
+         * server default) or `oldest`. Because the response is cached and the cache
+         * key is content-addressed on the query params, each `limit`/`offset`/`sort`
+         * combination is its own entry.
          */
-        getUserFollowers(userId: string, pagination?: PaginationParams): Promise<{
+        getUserFollowers(userId: string, pagination?: FollowGraphParams): Promise<{
             followers: User[];
             total: number;
             hasMore: boolean;
         }>;
         /**
-         * Get user following
+         * Get user following. `sort` behaves as in {@link getUserFollowers}.
          */
-        getUserFollowing(userId: string, pagination?: PaginationParams): Promise<{
+        getUserFollowing(userId: string, pagination?: FollowGraphParams): Promise<{
             following: User[];
             total: number;
             hasMore: boolean;
@@ -405,7 +426,7 @@ export declare function OxyServicesUserMixin<T extends typeof OxyServicesBase>(B
          * Get user mutuals ("followers you know" — users the authenticated viewer
          * follows who also follow `userId`). The viewer is derived server-side from auth.
          */
-        getUserMutuals(userId: string, pagination?: PaginationParams): Promise<{
+        getUserMutuals(userId: string, pagination?: FollowGraphParams): Promise<{
             mutuals: User[];
             total: number;
             hasMore: boolean;

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

@@ -22,6 +22,8 @@ export { assertSafePublicUrl, isBlockedIp, safeFetch, SsrfRejection, UpstreamErr
 export type { SafeFetchOptions, SafeFetchResult, SsrfCheckFail, SsrfCheckOk, SsrfCheckResult, } from './safeFetch';
 export { createOxyCors } from './cors';
 export type { OxyCorsOptions } from './cors';
+export { buildOxyCspDirectives, buildOxyPagesHeaders, createOxySecurityHeaders, formatOxyCspPolicy, OXY_CSP_BASELINE, } from './securityHeaders';
+export type { OxyCspDirective, OxyCspExtensions, OxyPagesHeadersOptions, OxySecurityHeadersOptions, } from './securityHeaders';
 export { verifySecret } from './verifySecret';
 export { registrableApex } from '../utils/registrableApex';
-export { buildIdpHubOrigin, buildHubSyncUrl, isIdpHubOrigin, isOfficialWebOrigin, normalizeOfficialReturnOrigin, parseHubSyncReturnUrl, } from '../utils/officialOrigins';
+export { isOfficialWebOrigin } from '../utils/officialOrigins';

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

@@ -0,0 +1,154 @@
+/**
+ * Shared security headers (Helmet + Content-Security-Policy) for Oxy backends.
+ *
+ * WHY THIS EXISTS
+ * ---------------
+ * A CSP only governs an origin that serves DOCUMENTS; on a JSON API it governs
+ * no browsing context. The Oxy origins that serve HTML through Cloudflare have
+ * so far either hand-written their own policy or shipped none at all, and two
+ * bugs follow from that:
+ *
+ *  1. THE CLOUDFLARE INSIGHTS BEACON IS BLOCKED BY A HAND-WRITTEN POLICY.
+ *     Cloudflare injects `<script src="https://static.cloudflareinsights.com/
+ *     beacon.min.js/...">` into HTML it proxies. No application code loads it,
+ *     so it cannot be allowlisted from the app side any other way, and an
+ *     origin whose policy says `script-src 'self'` logs
+ *     `Loading the script 'https://static.cloudflareinsights.com/beacon.min.js'
+ *     violates the following Content Security Policy directive: "script-src
+ *     'self'"` and collects nothing. The beacon needs BOTH hosts, and they are
+ *     different halves of the same feature: `static.cloudflareinsights.com`
+ *     serves the script (`script-src`), `cloudflareinsights.com` receives the
+ *     measurements (`connect-src`). Allowing only the script leaves the beacon
+ *     loading but unable to report, which looks fixed and is not. Verified in
+ *     production 2026-07-29: `mention.earth` serves HTML behind Cloudflare with
+ *     the beacon injected and `script-src 'self'` — blocked; `oxy.so` had
+ *     already allowlisted the same two hosts in its own static `_headers`,
+ *     independently, which is the divergence this baseline exists to end.
+ *
+ *  2. AN EXPLICIT DIRECTIVE SILENTLY REPLACES HELMET'S DEFAULT.
+ *     Writing `scriptSrc: ['https://example.com']` drops `'self'` — the page's
+ *     own bundle stops loading (or, worse, only some lazily-loaded chunk does,
+ *     so it ships). This helper makes that structurally impossible: callers can
+ *     only ADD sources to the Oxy baseline, never replace a directive, and they
+ *     cannot pass their own `contentSecurityPolicy` through to Helmet at all
+ *     (the option is typed `never`).
+ *
+ * WHAT IT PROVIDES
+ * ----------------
+ * `createOxySecurityHeaders(options)` returns the Helmet middleware with the
+ * Oxy-wide CSP baseline applied, plus per-app extensions merged (and deduped)
+ * into it. Everything Helmet does that is NOT the CSP (HSTS, frameguard,
+ * referrer policy, CORP/COOP, …) is passed straight through, so an app keeps
+ * full control of those.
+ *
+ * `buildOxyCspDirectives(extensions)` is the same resolution as a pure
+ * function, for the Oxy document origins that are NOT Express — a Next.js
+ * `headers()`, a Cloudflare Pages `_headers` generator — so one policy can
+ * cover them without a second implementation.
+ *
+ * SCOPE: mount this on backends that serve HTML. A JSON-only API gains nothing
+ * from a source-list CSP; harden those with the non-CSP headers instead
+ * (`hsts`, `noSniff`, `frameguard`, CORP) rather than adding directives that
+ * apply to no document.
+ *
+ * Node/Express-only: exported solely from `@oxyhq/core/server`.
+ */
+import type { RequestHandler } from 'express';
+import { type HelmetOptions } from 'helmet';
+/** The CSP directives an Oxy app may extend, in Helmet's camelCase spelling. */
+export type OxyCspDirective = 'baseUri' | 'connectSrc' | 'defaultSrc' | 'fontSrc' | 'formAction' | 'frameAncestors' | 'frameSrc' | 'imgSrc' | 'manifestSrc' | 'mediaSrc' | 'objectSrc' | 'scriptSrc' | 'scriptSrcAttr' | 'scriptSrcElem' | 'styleSrc' | 'styleSrcElem' | 'workerSrc';
+/**
+ * Per-app ADDITIONS to the Oxy baseline, keyed by directive. Values are merged
+ * into the baseline and deduped — they never replace it, so `'self'` (and the
+ * Cloudflare beacon hosts) cannot be lost. Extending a directive the baseline
+ * does not define seeds it with `'self'` first, for the same reason.
+ */
+export type OxyCspExtensions = Partial<Record<OxyCspDirective, readonly string[]>>;
+/**
+ * The Oxy-wide CSP baseline. Deliberately the floor every Oxy origin needs, not
+ * a superset of what any one app allows — permissive sources an individual app
+ * wants (`https:` images, `blob:` media, embed hosts, LiveKit) are that app's
+ * extension, so each widening stays visible at its call site.
+ *
+ * `style-src` carries `'unsafe-inline'` because react-native-web injects its
+ * stylesheet as inline `<style>` at runtime; without it every Oxy web app
+ * renders unstyled.
+ */
+export declare const OXY_CSP_BASELINE: Readonly<Partial<Record<OxyCspDirective, readonly string[]>>>;
+/**
+ * Resolve the effective CSP directives: the Oxy baseline, with each app
+ * extension merged in and deduped.
+ *
+ * Merge rules:
+ *  - A baseline directive is EXTENDED, never replaced — `'self'` and the
+ *    Cloudflare beacon hosts always survive.
+ *  - A directive absent from the baseline is seeded with `'self'`, so adding
+ *    (say) an embed host to `frame-src` cannot lock the origin out of itself.
+ *  - A directive whose baseline is exactly `'none'` is CLOSED: extending it
+ *    drops the sentinel, because `'none'` alongside any other source is
+ *    meaningless per the CSP spec. This is how an app that must be framable
+ *    opts back in with `frameAncestors: ["'self'"]`.
+ *
+ * @example
+ * ```ts
+ * buildOxyCspDirectives({ frameSrc: ['https://player.vimeo.com'] });
+ * // → { ..., 'frame-src': ["'self'", 'https://player.vimeo.com'], ... }
+ * ```
+ */
+export declare function buildOxyCspDirectives(extensions?: OxyCspExtensions): Record<string, string[]>;
+/**
+ * Serialize resolved CSP directives into the single-line header value browsers
+ * and Cloudflare `_headers` expect. Valueless directives (e.g.
+ * `upgrade-insecure-requests`) emit the name alone.
+ */
+export declare function formatOxyCspPolicy(directives: Record<string, string[]>): string;
+export interface OxyPagesHeadersOptions {
+    /** Per-app additions merged into {@link OXY_CSP_BASELINE}. */
+    csp?: OxyCspExtensions;
+    /**
+     * Emit `Strict-Transport-Security` (default `true`). Cloudflare Pages serves
+     * HTTPS only, so static deploys should keep this on.
+     */
+    hsts?: boolean;
+}
+/**
+ * Build a Cloudflare Pages `_headers` block for an Oxy HTML origin. Uses the
+ * same CSP resolution as {@link createOxySecurityHeaders} plus the non-CSP
+ * hardening headers Helmet would add on an Express HTML backend.
+ */
+export declare function buildOxyPagesHeaders(options?: OxyPagesHeadersOptions): string;
+export interface OxySecurityHeadersOptions {
+    /**
+     * Per-app additions to the Oxy CSP baseline. Merged, deduped, never
+     * replacing — see {@link buildOxyCspDirectives}.
+     */
+    csp?: OxyCspExtensions;
+    /**
+     * Everything Helmet does that is not the CSP: `hsts`, `frameguard`,
+     * `referrerPolicy`, `crossOriginResourcePolicy`, … Passed straight through.
+     *
+     * `contentSecurityPolicy` is typed `never` on purpose: the CSP is owned by
+     * this helper so the baseline cannot be replaced (nor the `'self'` guarantee
+     * bypassed) by an app that hands Helmet its own directive block. Extend it
+     * through `csp` instead.
+     */
+    helmet?: HelmetOptions & {
+        contentSecurityPolicy?: never;
+    };
+}
+/**
+ * Build the shared Oxy security-headers middleware: Helmet with the Oxy CSP
+ * baseline plus this app's extensions.
+ *
+ * @example
+ * ```ts
+ * app.use(createOxySecurityHeaders({
+ *   csp: {
+ *     connectSrc: ['https://api.example.com', 'wss://api.example.com'],
+ *     frameSrc: ['https://player.vimeo.com'],
+ *   },
+ *   helmet: { crossOriginResourcePolicy: { policy: 'cross-origin' } },
+ * }));
+ * ```
+ */
+export declare function createOxySecurityHeaders(options?: OxySecurityHeadersOptions): RequestHandler;

package/dist/types/session/accountDialogController.d.ts

@@ -231,21 +231,17 @@ export interface AccountDialogControllerOptions {
      * `SessionClient.registerAndActivate` (registration + activation only — no
      * provider-side durable persist/hydration).
      *
-     * This is the SIGN-IN commit: on an official web origin it may run the
-     * cross-origin hub-sync (a full-page redirect to `auth.oxy.so/sync`) that
-     * bootstraps silent OAuth restore on OTHER origins. A first sign-in on a web
-     * origin legitimately needs that. An account SWITCH does NOT — see
-     * {@link commitSwitchedSession}.
+     * This is the SIGN-IN commit: registers the session into the host's device
+     * set with durable persist + profile hydration. An account SWITCH uses
+     * {@link commitSwitchedSession} instead — see below.
      */
     commitSession?: (session: SessionLoginResponse) => Promise<void>;
     /**
      * Commit a minted graph SWITCH session into the host's session set — same
      * device-first registration + durable persist + profile hydration as
-     * {@link commitSession}, but IN-PLACE: it must NOT trigger the cross-origin
-     * hub-sync redirect. Switching into an account you already operate reuses the
-     * device credential that was already hub-synced at the original sign-in, so
-     * re-syncing is redundant and a full-page redirect on switch is the exact
-     * regression this separation prevents. Cross-tab/app propagation of the switch
+     * {@link commitSession}, but IN-PLACE: it must NOT re-run sign-in side effects
+     * that belong only to a fresh authorization (for example, a redundant full
+     * device-set reconcile on switch). Cross-tab/app propagation of the switch
      * still happens instantly via the server's device-scoped `session_state` /
      * `session_accounts_changed` socket broadcast — no navigation required.
      *
@@ -600,11 +596,9 @@ export declare class AccountDialogController {
      * consumer's commit funnel (durable persist + hydration); falls back to
      * `SessionClient.registerAndActivate` (registration + activation only).
      *
-     * A SWITCH (`opts.fromSwitch`) uses the IN-PLACE `commitSwitchedSession` funnel
-     * so it never runs the cross-origin hub-sync redirect; a SIGN-IN uses
-     * `commitSession` (which may hub-sync on an official web origin). When the
-     * switch funnel is not wired it falls back to the sign-in funnel, then to
-     * `registerAndActivate`.
+     * A SWITCH (`opts.fromSwitch`) uses the IN-PLACE `commitSwitchedSession` funnel;
+     * a SIGN-IN uses `commitSession`. When the switch funnel is not wired it falls
+     * back to the sign-in funnel, then to `registerAndActivate`.
      */
     private commitAuthorizedSession;
     private failSignIn;

package/dist/types/utils/apiUtils.d.ts

@@ -2,18 +2,39 @@
  * Utility functions for common API patterns
  */
 /**
- * Build URL search parameters from an object
+ * Build a plain query-parameter record from an object, stringifying values and
+ * dropping `undefined`/`null` entries.
+ *
+ * This is the shape `OxyServices.makeRequest` expects for a GET's `params`:
+ * `HttpService` inspects it with `Object.keys(...)` (both to decide whether to
+ * append a query string and to build the request's cache key), and
+ * `Object.keys(new URLSearchParams({ limit: '20' }))` is `[]` — a
+ * `URLSearchParams` exposes its entries through iterator methods, never as own
+ * enumerable properties. Passing one to `makeRequest` therefore silently drops
+ * the whole query string. Always hand `makeRequest` a plain record.
+ *
+ * Generic over the input object rather than taking `Record<string, unknown>`,
+ * because a TypeScript `interface` (`PaginationParams`, `FollowGraphParams`, …)
+ * has no implicit index signature and so is not assignable to that type.
+ */
+export declare function buildQueryParams<T extends object>(params: T): Record<string, string>;
+/**
+ * Build URL search parameters from an object.
+ *
+ * For building a URL string only — see {@link buildQueryParams} for the shape
+ * `makeRequest` needs.
+ *
  * @param params Object with parameter key-value pairs
  * @returns URLSearchParams instance
  */
-export declare function buildSearchParams(params: Record<string, any>): URLSearchParams;
+export declare function buildSearchParams<T extends object>(params: T): URLSearchParams;
 /**
  * Build URL with search parameters
  * @param baseUrl Base URL
  * @param params Object with parameter key-value pairs
  * @returns Complete URL with search parameters
  */
-export declare function buildUrl(baseUrl: string, params?: Record<string, any>): string;
+export declare function buildUrl<T extends object>(baseUrl: string, params?: T): string;
 /**
  * Common pagination parameters
  */
@@ -22,11 +43,32 @@ export interface PaginationParams {
     offset?: number;
 }
 /**
- * Build pagination search parameters
+ * Ordering for the follow-graph list endpoints (`/users/:id/followers`,
+ * `/users/:id/following`, `/users/:id/mutuals`).
+ *
+ * - `recent` — newest follow edge first (the server default).
+ * - `oldest` — oldest follow edge first.
+ */
+export type FollowGraphSort = 'recent' | 'oldest';
+/**
+ * Pagination plus the follow-graph ordering.
+ *
+ * Kept separate from {@link PaginationParams}, which is shared by endpoints
+ * that have no `sort` at all.
+ */
+export interface FollowGraphParams extends PaginationParams {
+    sort?: FollowGraphSort;
+}
+/**
+ * Build pagination query parameters.
+ *
+ * Returns a plain record — NOT a `URLSearchParams` — because that is the only
+ * shape `makeRequest`/`HttpService` can read. See {@link buildQueryParams}.
+ *
  * @param params Pagination parameters
- * @returns URLSearchParams with pagination
+ * @returns Query record with pagination
  */
-export declare function buildPaginationParams(params: PaginationParams): URLSearchParams;
+export declare function buildPaginationParams(params: PaginationParams): Record<string, string>;
 /**
  * Common API response wrapper
  */

package/dist/types/utils/oauthPkce.d.ts

@@ -43,10 +43,18 @@ export interface BuildOAuthAuthorizeUrlParams {
     /** The PKCE `codeChallenge` from {@link generatePkcePair}. */
     codeChallenge: string;
     /**
-     * OAuth `prompt` parameter. Use `none` for silent cross-origin session restore
-     * (no UI when the IdP hub already has a session + grant).
+     * OAuth `prompt` parameter — `login` forces a fresh authentication even when
+     * the IdP already has a session, `consent` forces the consent screen even for
+     * an already-granted scope. Both are ordinary OAuth/OIDC and are here for
+     * third-party relying parties building their own authorize link.
+     *
+     * `'none'` is deliberately NOT in this union. It is the silent-SSO value, and
+     * it was the only value this SDK ever sent — from the cold-boot cross-origin
+     * restore deleted in #691 phase 7b. Accepting it again would hand consumers a
+     * one-line rebuild of the automatic, gesture-less full-page bounce to the IdP
+     * that the popup transport exists to eliminate.
      */
-    prompt?: 'none' | 'login' | 'consent';
+    prompt?: 'login' | 'consent';
     /**
      * How the IdP should deliver the authorization response. Omitted (the
      * default) means the ordinary top-level redirect back to `redirectUri`.
@@ -95,10 +103,6 @@ export declare const OXY_OAUTH_STATE_STORAGE_KEY = "oxy_oauth_state";
 export declare const OXY_OAUTH_CODE_VERIFIER_STORAGE_KEY = "oxy_oauth_code_verifier";
 /** `sessionStorage` key — the exact `redirect_uri` sent on the authorize request. */
 export declare const OXY_OAUTH_REDIRECT_URI_STORAGE_KEY = "oxy.oauth_redirect_uri";
-/** `sessionStorage` key — at most one silent OAuth attempt per navigation. */
-export declare const OXY_SILENT_OAUTH_ATTEMPTED_KEY = "oxy.silent_oauth_attempted";
-/** `sessionStorage` key — blocks further cross-origin auto-restore in this tab. */
-export declare const OXY_CROSS_ORIGIN_RESTORE_ATTEMPTED_KEY = "oxy.cross_origin_restore_attempted";
 /**
  * `sessionStorage` key for the in-app path to return to after an authorize
  * round trip. See {@link persistOAuthReturnPath}.

package/dist/types/utils/officialOrigins.d.ts

@@ -1,23 +1,13 @@
 /**
- * Official first-party web origin allowlist — shared by hub-ticket issuance,
- * OAuth redirect validation, and cross-origin session restore.
+ * Official first-party web origin allowlist — shared by OAuth redirect
+ * validation and the server-side trusted-origin checks.
  */
-export declare function buildIdpHubOrigin(): string;
-/** Whether the current web origin is the central IdP hub (`auth.oxy.so`). */
-export declare function isIdpHubOrigin(): boolean;
 /**
  * Whether an origin is a loopback / local-dev origin (`localhost`, `127.0.0.1`,
- * or `[::1]` on any port, http or https). Local dev must never be bounced to a
- * hosted IdP for cross-origin session restore.
+ * or `[::1]` on any port, http or https).
  */
 export declare function isLoopbackOrigin(origin: string): boolean;
 /** Whether an origin belongs to the official Oxy web ecosystem. */
 export declare function isOfficialWebOrigin(origin: string): boolean;
-/** Normalize and validate a return URL against official origins. Returns origin only. */
-export declare function normalizeOfficialReturnOrigin(raw: string): string | null;
-/** Validate a hub-sync return URL; returns the full normalized URL string. */
-export declare function parseHubSyncReturnUrl(raw: string | null): string | null;
-/** Build auth.oxy.so/sync redirect URL with a one-time hub ticket. */
-export declare function buildHubSyncUrl(ticket: string, returnUrl?: string): string;
 /** @deprecated Use {@link isOfficialWebOrigin}. */
 export declare const isAllowedDeviceJoinOrigin: typeof isOfficialWebOrigin;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oxyhq/core",
-  "version": "12.11.1",
+  "version": "13.2.0",
   "description": "OxyHQ SDK Foundation — API client, authentication, cryptographic identity, and shared utilities",
   "main": "dist/cjs/index.js",
   "module": "dist/esm/index.js",
@@ -115,8 +115,8 @@
   "dependencies": {
     "@noble/ciphers": "^1.3.0",
     "@noble/hashes": "^1.8.0",
-    "@oxyhq/contracts": "^0.18.0",
-    "@oxyhq/protocol": "^0.1.5",
+    "@oxyhq/contracts": "^0.19.0",
+    "@oxyhq/protocol": "^0.1.6",
     "bip39": "^3.1.0",
     "buffer": "^6.0.3",
     "elliptic": "^6.6.1",
@@ -131,7 +131,8 @@
     "expo-crypto": "*",
     "expo-secure-store": "*",
     "express": "^4.0.0",
-    "express-rate-limit": "^7.0.0"
+    "express-rate-limit": "^7.0.0",
+    "helmet": "^8.0.0"
   },
   "peerDependenciesMeta": {
     "@react-native-async-storage/async-storage": {
@@ -145,6 +146,9 @@
     },
     "express": {
       "optional": true
+    },
+    "helmet": {
+      "optional": true
     }
   },
   "devDependencies": {
@@ -160,6 +164,7 @@
     "express-rate-limit": "^8.6.0",
     "regexpu-core": "^6.4.0",
     "release-it": "^19.0.6",
-    "typescript": "^5.9.2"
+    "typescript": "^5.9.2",
+    "helmet": "^8.3.0"
   }
 }

package/src/index.ts

@@ -59,10 +59,15 @@ export type {
     CommonsApprovalInfo,
     CommonsApprovalSubjectAccount,
     CommonsSignInActionResult,
-    CommonsDenyReason,
     CommonsOAuthFinalizeResult,
     CommonsDeliveryResult,
 } from './mixins/OxyServices.auth';
+// `denyCommonsSignIn`'s reason parameter is typed by `CommonsDenyReason`, which
+// is a WIRE contract shared with the API (the request schema of
+// `POST /auth/session/deny/:authorizeCode` and the persisted
+// `AuthSession.deniedReason` enum read the same declaration). It lives in
+// `@oxyhq/contracts` and is NOT re-exported here: consumers import API contract
+// types directly from `@oxyhq/contracts`, per the package boundary rule.
 // Push-token registration (Expo push tokens — never raw APNs/FCM device tokens).
 export type {
     PushTokenPlatform,
@@ -463,6 +468,7 @@ export { translate } from './i18n';
 // API request / URL helpers
 // ---------------------------------------------------------------------------
 export {
+    buildQueryParams,
     buildSearchParams,
     buildUrl,
     buildPaginationParams,
@@ -470,6 +476,8 @@ export {
 } from './utils/apiUtils';
 export type {
     PaginationParams,
+    FollowGraphParams,
+    FollowGraphSort,
     ApiResponse,
     ErrorResponse,
 } from './utils/apiUtils';
@@ -601,8 +609,6 @@ export {
     OXY_OAUTH_STATE_STORAGE_KEY,
     OXY_OAUTH_CODE_VERIFIER_STORAGE_KEY,
     OXY_OAUTH_REDIRECT_URI_STORAGE_KEY,
-    OXY_SILENT_OAUTH_ATTEMPTED_KEY,
-    OXY_CROSS_ORIGIN_RESTORE_ATTEMPTED_KEY,
     OXY_OAUTH_RETURN_PATH_STORAGE_KEY,
     normalizeOAuthRedirectUri,
     canonicalizeOAuthRedirectUri,
@@ -615,22 +621,11 @@ export {
 export type { PkcePair, BuildOAuthAuthorizeUrlParams } from './utils/oauthPkce';
 
 export {
-    buildIdpHubOrigin,
-    buildHubSyncUrl,
-    isIdpHubOrigin,
     isLoopbackOrigin,
     isOfficialWebOrigin,
     isAllowedDeviceJoinOrigin,
-    normalizeOfficialReturnOrigin,
-    parseHubSyncReturnUrl,
 } from './utils/officialOrigins';
 
-export {
-    syncHubAfterSignIn,
-    redeemHubTicketOnHub,
-} from './session/hubSync';
-export type { SyncHubAfterSignInOptions } from './session/hubSync';
-
 // ---------------------------------------------------------------------------
 // Session sync (device-scoped multi-account session client)
 // ---------------------------------------------------------------------------

package/src/mixins/OxyServices.auth.ts

@@ -4,7 +4,12 @@
  * Supports password-based login (email/username) and public key challenge-response.
  */
 import type { User } from '../models/interfaces';
-import type { UserNameResponse, LoginResult, LoginSessionResult } from '@oxyhq/contracts';
+import type {
+  UserNameResponse,
+  LoginResult,
+  LoginSessionResult,
+  CommonsDenyReason,
+} from '@oxyhq/contracts';
 import { loginResultSchema, safeParseContract } from '@oxyhq/contracts';
 import type { SessionLoginResponse } from '../models/session';
 import type { OxyServicesBase } from '../OxyServices.base';
@@ -336,18 +341,6 @@ export interface CommonsSignInActionResult {
   success: boolean;
 }
 
-/**
- * Why the approver denied a "Sign in with Oxy" request. A CLOSED set — the deny
- * endpoint is unauthenticated, so it accepts no free-form text:
- *
- *  - `'declined'` the approver rejected a request they recognised ("Not now").
- *  - `'not_me'`   the approver did not start the request ("This wasn't me").
- *                 The only value that records the denial as suspicious rather
- *                 than an ordinary cancel, so a UI may only offer it where the
- *                 user genuinely said so.
- */
-export type CommonsDenyReason = 'declined' | 'not_me';
-
 /**
  * Result of finalizing an approved, OAuth-bound "Sign in with Oxy" request.
  *