@oxy.so/core 1.18.0 → 3.0.0

package/dist/esm/server/namespaces.js

@@ -0,0 +1,206 @@
+import { AssetsApi } from '../api/assets.js';
+import { NotificationsApi } from '../api/notifications.js';
+import { LinkedAccountsApi } from '../api/linkedAccounts.js';
+import { AgencyApi } from '../api/agency.js';
+import { ReputationApi } from '../api/reputation.js';
+import { ServiceAssetMetadataError, ServiceLinkedDownloadUrlError } from '../OxyServices.errors.js';
+import { extractErrorStatus } from '../utils/errorUtils.js';
+import { logger } from '../logger/index.js';
+/** Server-side cap of `POST /assets/service/by-ids`. */
+const SERVICE_ASSET_METADATA_CHUNK_SIZE = 100;
+/** Server-side cap of `POST /assets/service/by-sha256`. */
+const SERVICE_ASSET_METADATA_BY_SHA_CHUNK_SIZE = 100;
+/** Server-side cap of `POST /assets/service/linked-url`. */
+const SERVICE_LINKED_DOWNLOAD_URL_CHUNK_SIZE = 25;
+const SHA256_HEX_PATTERN = /^[a-f0-9]{64}$/;
+const REPUTATION_CACHE_PREFIX = 'GET:/reputation/';
+function lane(ctx) {
+    if (!ctx.service) {
+        throw new Error('This call needs a service credential (OxyServer from @oxy.so/core/server)');
+    }
+    return ctx.service;
+}
+function chunk(items, size) {
+    const chunks = [];
+    for (let i = 0; i < items.length; i += size)
+        chunks.push(items.slice(i, i + size));
+    return chunks;
+}
+function uniqueIds(ids) {
+    return Array.from(new Set(ids.filter((id) => typeof id === 'string' && id.trim().length > 0)));
+}
+export class ServerAssetsApi extends AssetsApi {
+    /**
+     * Resolve many asset ids to their content-addressed metadata (`sha256`,
+     * `mime`, `size`, `status`) via `POST /assets/service/by-ids`, one call per
+     * chunk of 100. Service token with `files:read`.
+     *
+     * The server omits unknown/deleted ids, so a short result is normal — map by
+     * `id`. FAILURE IS NOT ABSENCE: a failed chunk throws
+     * {@link ServiceAssetMetadataError} carrying the ids it could not resolve,
+     * unless `{ partial: true }` asks for best-effort. Never cached.
+     */
+    async metadataByIds(ids, options = {}) {
+        const unique = uniqueIds(ids);
+        if (unique.length === 0)
+            return [];
+        const unresolvedIds = [];
+        const statuses = [];
+        let firstError;
+        const settled = await Promise.all(chunk(unique, SERVICE_ASSET_METADATA_CHUNK_SIZE).map(async (part) => {
+            try {
+                const entries = await lane(this.ctx).request('POST', '/assets/service/by-ids', { ids: part });
+                return Array.isArray(entries) ? entries : [];
+            }
+            catch (error) {
+                const status = extractErrorStatus(error);
+                logger.warn('assets.metadataByIds: chunk failed', {
+                    method: 'assets.metadataByIds',
+                    chunkSize: part.length,
+                    status,
+                    partial: options.partial === true,
+                    error: error instanceof Error ? error.message : String(error),
+                });
+                unresolvedIds.push(...part);
+                if (typeof status === 'number')
+                    statuses.push(status);
+                firstError ?? (firstError = error);
+                return [];
+            }
+        }));
+        if (unresolvedIds.length > 0 && options.partial !== true) {
+            throw new ServiceAssetMetadataError(unresolvedIds, statuses, firstError);
+        }
+        return settled.flat();
+    }
+    /**
+     * Mint short-lived direct download URLs for files the calling application's
+     * own users attached to it (`POST /assets/service/linked-url`, scope
+     * `files:linked:read`). The ONLY way a service token reaches file bytes.
+     *
+     * A URL comes back only for a file whose OWN OWNER linked it to this
+     * application; every other id is omitted, and the route answers identically
+     * for "no such file" and "not yours". ABSENCE IS A REFUSAL, not a fact about
+     * the file: decide what to tell your user from your own entitlement record.
+     * A failed chunk throws {@link ServiceLinkedDownloadUrlError}; there is no
+     * partial mode. Never cached — each URL is a live credential.
+     */
+    async linkedDownloadUrls(ids) {
+        const unique = uniqueIds(ids);
+        if (unique.length === 0)
+            return [];
+        const unresolvedIds = [];
+        const statuses = [];
+        let firstError;
+        const settled = await Promise.all(chunk(unique, SERVICE_LINKED_DOWNLOAD_URL_CHUNK_SIZE).map(async (part) => {
+            try {
+                const entries = await lane(this.ctx).request('POST', '/assets/service/linked-url', { ids: part });
+                return Array.isArray(entries) ? entries : [];
+            }
+            catch (error) {
+                const status = extractErrorStatus(error);
+                // `chunkSize` and `status`, never the ids and never a `url`: a minted
+                // URL in a log line is a credential in a log line.
+                logger.warn('assets.linkedDownloadUrls: chunk failed', {
+                    method: 'assets.linkedDownloadUrls',
+                    chunkSize: part.length,
+                    status,
+                    error: error instanceof Error ? error.message : String(error),
+                });
+                unresolvedIds.push(...part);
+                if (typeof status === 'number')
+                    statuses.push(status);
+                firstError ?? (firstError = error);
+                return [];
+            }
+        }));
+        if (unresolvedIds.length > 0) {
+            throw new ServiceLinkedDownloadUrlError(unresolvedIds, statuses, firstError);
+        }
+        return settled.flat();
+    }
+    /**
+     * Reverse content-address lookup: resolve `sha256` digests to the servable
+     * asset holding each (`POST /assets/service/by-sha256`, scope `files:read`),
+     * with a public `url` for active public assets. Malformed hashes are dropped
+     * client-side; the server omits unknown ones, so map by `sha256`. A failed
+     * chunk is logged and skipped. Never cached.
+     */
+    async metadataBySha256(sha256s) {
+        const unique = Array.from(new Set(sha256s
+            .filter((sha) => typeof sha === 'string')
+            .map((sha) => sha.trim().toLowerCase())
+            .filter((sha) => SHA256_HEX_PATTERN.test(sha))));
+        if (unique.length === 0)
+            return [];
+        const settled = await Promise.all(chunk(unique, SERVICE_ASSET_METADATA_BY_SHA_CHUNK_SIZE).map(async (part) => {
+            try {
+                const entries = await lane(this.ctx).request('POST', '/assets/service/by-sha256', { sha256s: part });
+                return Array.isArray(entries) ? entries : [];
+            }
+            catch (error) {
+                logger.warn('assets.metadataBySha256: chunk failed, continuing with remaining chunks', {
+                    method: 'assets.metadataBySha256',
+                    chunkSize: part.length,
+                    status: extractErrorStatus(error),
+                    error: error instanceof Error ? error.message : String(error),
+                });
+                return [];
+            }
+        }));
+        return settled.flat();
+    }
+}
+export class ServerNotificationsApi extends NotificationsApi {
+    /**
+     * Create a notification (`POST /notifications`; the application needs
+     * `notifications:write`). `type` is one of `OXY_NOTIFICATION_TYPES` from
+     * `@oxy.so/contracts` — `system` for a message from an Oxy service about the
+     * recipient's own account.
+     */
+    async create(data) {
+        const res = await lane(this.ctx).request('POST', '/notifications', data);
+        return res.notification;
+    }
+}
+export class ServerLinkedAccountsApi extends LinkedAccountsApi {
+    /**
+     * A user's live linked accounts, each with the federated shadow user Oxy holds
+     * for it (`federatedUserId`). Needs the privileged `linked-accounts:read`.
+     */
+    async forUser(userId) {
+        return lane(this.ctx).request('GET', `/linked-accounts/by-user/${encodeURIComponent(userId)}`);
+    }
+}
+export class ServerAgencyApi extends AgencyApi {
+    /**
+     * Product backend → Oxy: trade the signed-in requester's access token for a
+     * one-use assertion naming `agentId` (ADR 0025), authenticated with this
+     * service's credential. `subjectToken` goes to Oxy only, in the body; never
+     * forward it anywhere else. Not retried: a refusal is an answer, and the
+     * caller mints per turn.
+     */
+    async mintRequesterAssertion(input) {
+        return lane(this.ctx).request('POST', '/internal/native-agents/requester-assertions', { agentId: input.agentId, subjectToken: input.subjectToken }, { retry: false, timeout: 5000 });
+    }
+    /**
+     * Audience → Oxy: verify, live-revalidate and CONSUME a present-requester
+     * assertion (ADR 0025). A second call with the same assertion answers
+     * `active: false`. Authenticated with the audience's own service credential.
+     */
+    async introspectRequesterAssertion(input) {
+        return lane(this.ctx).request('POST', '/internal/native-agents/requester-assertions/introspect', { assertion: input.assertion, presenter: input.presenter }, { retry: false, timeout: 5000 });
+    }
+}
+export class ServerReputationApi extends ReputationApi {
+    /**
+     * Award (or penalise) reputation to a user by `actionType`. Service token with
+     * `reputation:write` only — people never award reputation, and nobody at Oxy
+     * moves it by hand. Invalidates cached reputation reads.
+     */
+    async award(input) {
+        const res = await lane(this.ctx).request('POST', '/reputation/award', input);
+        this.ctx.oxy.cache.deletePrefix(REPUTATION_CACHE_PREFIX);
+        return res.transaction;
+    }
+}

package/dist/esm/server/rateLimit.js

@@ -116,7 +116,7 @@ function hashAnonymousIp(ip) {
  *
  * Only identities that came from a server-validated session or a verified
  * service token/delegation may pick a bucket. `req.sessionId` is the marker
- * for the former: `oxy.auth()` sets it only after `validateSession()` came
+ * for the former: `server.middleware.auth()` sets it only after `session.validate()` came
  * back valid, so requiring it here means an identity written by some OTHER
  * middleware — which this package cannot vouch for — shares the anonymous
  * per-IP bucket rather than getting the authenticated quota.
@@ -156,7 +156,7 @@ export function createOxyRateLimit(oxy, options = {}) {
     // Idempotent optional-auth resolver. Reuses the SAME session resolution as
     // every protected route, so the limiter keys by the real user identity.
     //
-    // `createOptionalOxyAuth` — NOT the raw `oxy.auth({ optional: true })` —
+    // `createOptionalOxyAuth` — NOT the raw `server.middleware.auth({ optional: true })` —
     // because only the former skips resolution when a preceding middleware has
     // already resolved a user. The raw middleware writes `req.userId = null` on
     // every request it cannot authenticate, and because it mutates the shared

package/dist/esm/server/requesterAssertion.js

@@ -2,7 +2,7 @@
  * Present-requester assertions (ADR 0025).
  *
  * A first-party product backend holding a signed-in person's live Oxy session
- * trades it with Oxy (`OxyServices.mintRequesterAssertion`) for a one-use,
+ * trades it with Oxy (`server.agency.mintRequesterAssertion`) for a one-use,
  * short-lived `OXY-REQUESTER+JWT`, and sends that — never the person's bearer —
  * to the audience service (Alia) beside its own service token. The audience
  * mounts {@link createOxyRequesterAssertionAuth} after `createOxyAuthMiddleware`
@@ -258,8 +258,8 @@ function singleHeader(req, name) {
  * token. Mount it after `createOxyAuthMiddleware`. Without the header it does
  * nothing, so it composes with every other lane.
  *
- * `introspector` must be an `OxyServices` configured with THIS service's own
- * credential (`configureServiceAuth`): Oxy only lets the audience's application
+ * `introspector` is this service's `OxyServer`, holding THIS service's own
+ * credential: Oxy only lets the audience's application
  * consume an assertion.
  */
 export function createOxyRequesterAssertionAuth(introspector, options) {
@@ -268,7 +268,7 @@ export function createOxyRequesterAssertionAuth(introspector, options) {
     const resolver = () => {
         resolvePublicKey ?? (resolvePublicKey = createOxyJwksKeyResolver({
             jwksUrl: options.jwksUrl
-                ?? new URL('/capabilities/.well-known/jwks.json', introspector.getBaseURL()).toString(),
+                ?? new URL('/capabilities/.well-known/jwks.json', introspector.baseURL).toString(),
         }));
         return resolvePublicKey;
     };
@@ -320,7 +320,7 @@ export function createOxyRequesterAssertionAuth(introspector, options) {
         }
         let introspection;
         try {
-            introspection = await introspector.introspectRequesterAssertion({
+            introspection = await introspector.agency.introspectRequesterAssertion({
                 assertion,
                 presenter: { applicationId: serviceApp.appId, credentialId: serviceApp.credentialId },
             });

package/dist/esm/server/securityHeaders.js

@@ -313,10 +313,10 @@ const MAX_INLINE_SCRIPT_HASHES = 8;
  * react-native-web's runtime stylesheet, and a style hash would silently switch
  * that off and render every Oxy web app unstyled.)
  */
-/** Passkeys for this origin itself; every other powerful feature off. */
+/** Every powerful feature off, WebAuthn included: Oxy has no passkeys (ADR 0030). */
 const SENSITIVE_PERMISSIONS_POLICY = [
-    'publickey-credentials-get=(self)',
-    'publickey-credentials-create=(self)',
+    'publickey-credentials-get=()',
+    'publickey-credentials-create=()',
     'camera=()',
     'microphone=()',
     'geolocation=()',

package/dist/esm/server/traffic.js

@@ -1,8 +1,8 @@
 import { observeNodeHttp, withoutNodeHttpObservation } from './trafficNodeHttp.js';
 import { observeTrafficSocket, observeTrafficWebSocket } from '@oxy.so/telemetry/socket';
 import { randomUUID } from 'node:crypto';
-import { OxyServices } from '../OxyServices.js';
-// Static, unlike the lazy import in `mixins/OxyServices.auth.ts`: that module is
+import { OxyServer } from './OxyServer.js';
+// Static, like `OxyServer`'s own import: this module is
 // reachable from the root barrel, which ships to React Native, so pulling
 // `node:crypto` in eagerly there would cost every mobile bundle. This file is
 // server-only and the server barrel already exports `./workloadIdentity`, so
@@ -41,12 +41,12 @@ export function createEcosystemTraffic(options) {
     if (!options.credential && (!apiKey || !apiSecret) && !canAttestWorkloadIdentity()) {
         throw new Error('Ecosystem activity needs one of: an OXY_ACTIVITY_API_KEY and OXY_ACTIVITY_API_SECRET pair, an OXY_SERVICE_API_KEY and OXY_SERVICE_API_SECRET pair, or a workload identity this process can attest (ADR 0026).');
     }
-    const oxy = new OxyServices({ baseURL });
-    // Left unconfigured when there is no pair on purpose: `getServiceToken()`
+    const oxy = new OxyServer({ baseURL });
+    // Left unconfigured when there is no pair on purpose: `serviceToken()`
     // attests instead of being handed half a credential to fail on.
     if (apiKey && apiSecret)
         oxy.configureServiceAuth(apiKey, apiSecret);
-    const credential = options.credential ?? (() => oxy.getServiceToken());
+    const credential = options.credential ?? (() => oxy.serviceToken());
     const fetcher = globalThis.fetch.bind(globalThis);
     const instanceId = randomUUID();
     const location = options.location ?? infrastructureLocation(region);
@@ -126,6 +126,7 @@ export function createEcosystemTraffic(options) {
             return cleanup;
         },
         async stop() { if (stopped)
-            return; stopped = true; cleanups.forEach(cleanup => cleanup()); cleanups.clear(); clearInterval(timer); clearInterval(heartbeatTimer); await flush(); await heartbeat(true); },
+            return; stopped = true; for (const cleanup of cleanups)
+            cleanup(); cleanups.clear(); clearInterval(timer); clearInterval(heartbeatTimer); await flush(); await heartbeat(true); },
     };
 }

package/dist/esm/server/trafficNodeHttp.js

@@ -63,8 +63,8 @@ export function observeNodeHttp(collector, service, region, resolveEndpoint) {
     const patches = [http, https].map(module => {
         const request = module.request;
         const get = module.get;
-        const wrappedRequest = function (...args) { return safelyObserve(request.apply(module, args)); };
-        const wrappedGet = function (...args) { return safelyObserve(get.apply(module, args)); };
+        const wrappedRequest = ((...args) => safelyObserve(request.apply(module, args)));
+        const wrappedGet = ((...args) => safelyObserve(get.apply(module, args)));
         module.request = wrappedRequest;
         module.get = wrappedGet;
         return () => {
@@ -75,5 +75,11 @@ export function observeNodeHttp(collector, service, region, resolveEndpoint) {
         };
     });
     syncBuiltinESMExports();
-    return () => { patches.forEach(restore => restore()); restoreRequests.forEach(restore => restore()); syncBuiltinESMExports(); };
+    return () => {
+        for (const restore of patches)
+            restore();
+        for (const restore of restoreRequests)
+            restore();
+        syncBuiltinESMExports();
+    };
 }

package/dist/esm/server/userInvalidation.js

@@ -6,8 +6,8 @@
  * Every Oxy backend caches Oxy identity, and none of them find out when it
  * changes. The `OxyServices` GET response cache holds `GET /users/:id` and
  * `GET /profiles/username/:name` for five minutes; it is swept when THIS process
- * writes the profile (the `evictOxyIdentityCache` calls in the user and accounts
- * mixins) and never when somebody else does — which is the normal case, since
+ * writes the profile (the `evictOxyIdentityCache` calls in the `users` and
+ * `accounts` namespaces) and never when somebody else does — which is the normal case, since
  * profiles are edited in Oxy's own apps. So an avatar or display-name change is
  * invisible to every consuming backend for up to five minutes, per process.
  *
@@ -34,11 +34,11 @@
  *     // node-redis
  *     await subscriber.subscribe(
  *       OXY_USER_INVALIDATION_CHANNEL,
- *       createOxyUserInvalidationHandler({ oxy: oxyClient }),
+ *       createOxyUserInvalidationHandler({ oxy: server }),
  *     );
  *
  *     // ioredis
- *     const handle = createOxyUserInvalidationHandler({ oxy: oxyClient });
+ *     const handle = createOxyUserInvalidationHandler({ oxy: server });
  *     await subscriber.subscribe(OXY_USER_INVALIDATION_CHANNEL);
  *     subscriber.on('message', (_channel, raw) => handle(raw));
  *
@@ -130,7 +130,7 @@ export function createOxyUserInvalidationHandler(options = {}) {
         }
         if (oxy) {
             try {
-                evictOxyIdentityCache(oxy, event.userId);
+                evictOxyIdentityCache(oxy.http, event.userId);
             }
             catch (error) {
                 // A cache sweep must never cost us the app-specific eviction below.

package/dist/esm/session/accountDialogController.js

@@ -20,8 +20,8 @@
  *     account` pair) and the two removals an account id cannot name —
  *     `signOutContext` and `signOutPrincipal`;
  *   - the "Sign in with Oxy" device flow (same-device shared-keychain via
- *     `oxyServices.signInWithSharedIdentity`, else the cross-device QR handoff
- *     via `startCommonsSignIn` → poll → `claimSessionByToken`);
+ *     `oxy.auth.signInWithSharedIdentity`, else the cross-device QR handoff
+ *     via `oxy.auth.commons.start` → poll → `oxy.auth.claimSession`);
  *   - AUTOMATIC delivery selection for that flow (issue #691): the user presses
  *     ONE primary action and the controller — not the user — picks how the
  *     request reaches their Commons identity, by gathering the facts
@@ -37,10 +37,10 @@
  *     (native only, via the injected `canOpenApp` probe), so the QR view can
  *     offer a "Get Commons" fallback instead of a same-device dead end.
  *
- * Sign-in is passkey (WebAuthn) or the Commons QR / shared-keychain handoff —
- * password, social login, and 2FA were removed ecosystem-wide. Account
- * creation (`signup` view) is the same two identity backends: a passkey
- * ceremony on web, or a Commons-created identity.
+ * Sign-in is by email (a code or a link), an optional password and an
+ * optional authenticator, or the Commons QR / shared-keychain handoff. Account
+ * creation (`signup` view) is a username and a confirmed email, or a
+ * Commons-created identity.
  *
  * The controller owns NO surface PRESENTATION: whether the account dialog is
  * mounted, visible, or dismissed is the job of the shared surface stack
@@ -240,9 +240,9 @@ export class AccountDialogController {
         // has returned; `ensureActiveToken` plants it async later), so the
         // device-state subscription alone cannot observe the signed-out → signed-in
         // edge. Observe the SDK-canonical readiness signal directly — a change to
-        // `oxyServices.getAccessToken()`, the `hasAccessToken` term of
+        // `oxy.session.accessToken`, the `hasAccessToken` term of
         // `OxyContext.canUsePrivateApi`.
-        this.unsubscribeTokens = this.oxyServices.onTokensChanged(() => {
+        this.unsubscribeTokens = this.oxyServices.session.onChange(() => {
             this.reconcileAuth();
         });
         // Initial projection is device-only. `refresh()` fetches the graph IFF a
@@ -283,7 +283,7 @@ export class AccountDialogController {
      * Whether a PRIVATE endpoint may be called right now. Mirrors the
      * `hasAccessToken` term of `OxyContext.canUsePrivateApi`
      * (`authResolved && isAuthenticated && tokenReady && hasAccessToken`, where
-     * `hasAccessToken = Boolean(oxyServices.getAccessToken())`): a planted bearer
+     * `hasAccessToken = Boolean(oxy.session.accessToken)`): a planted bearer
      * is the only term that decides whether a request carries auth — the other
      * three are provider render-lifecycle gates with no headless equivalent.
      *
@@ -294,7 +294,7 @@ export class AccountDialogController {
      * on this.
      */
     isAuthenticated() {
-        return Boolean(this.oxyServices.getAccessToken());
+        return Boolean(this.oxyServices.session.accessToken);
     }
     /**
      * Reconcile the account graph against the current auth-readiness edge. On the
@@ -381,7 +381,7 @@ export class AccountDialogController {
     add() {
         this.setView('add');
     }
-    /** Switch to the "create account" view (passkey / Commons signup entry). */
+    /** Switch to the "create account" view (email / Commons signup entry). */
     startSignup() {
         this.setView('signup');
     }
@@ -630,7 +630,7 @@ export class AccountDialogController {
         try {
             // Minted WITHOUT planting the bearer: `completeSignIn` installs it only if
             // this attempt is still the current one when the mint returns.
-            const session = await this.oxyServices.signInWithSharedIdentity({ plantTokens: false });
+            const session = await this.oxyServices.auth.signInWithSharedIdentity({ plantTokens: false });
             if (!this.isCurrentAttempt(attempt))
                 return;
             if (session) {
@@ -727,7 +727,7 @@ export class AccountDialogController {
         this.setSignIn({ ...IDLE_SIGN_IN_FACTS, phase: 'starting' });
         let handle;
         try {
-            handle = await this.oxyServices.startCommonsSignIn({ clientId: this.clientId });
+            handle = await this.oxyServices.auth.commons.start({ clientId: this.clientId });
         }
         catch (error) {
             if (!this.isCurrentAttempt(attempt))
@@ -835,7 +835,7 @@ export class AccountDialogController {
         if (!this.isAuthenticated())
             return 0;
         try {
-            const result = await this.oxyServices.deliverCommonsSignIn(authorizeCode);
+            const result = await this.oxyServices.auth.commons.deliver(authorizeCode);
             // `delivered: false` with `targets > 0` is a transport failure, not a
             // reachable install — the shared helper owns that rule so the surface
             // can never park a user on "check your phone" for a push that failed.
@@ -932,7 +932,7 @@ export class AccountDialogController {
      */
     async withdrawRequest(authorizeCode) {
         try {
-            await this.oxyServices.denyCommonsSignIn(authorizeCode);
+            await this.oxyServices.auth.commons.deny(authorizeCode);
         }
         catch (error) {
             logger.debug('[AccountDialogController] request withdrawal failed', { component: 'AccountDialogController' }, error);
@@ -967,7 +967,7 @@ export class AccountDialogController {
                 return;
             }
             try {
-                const status = await this.oxyServices.pollCommonsSignIn(sessionToken);
+                const status = await this.oxyServices.auth.commons.poll(sessionToken);
                 if (this.signInToken !== sessionToken)
                     return; // cancelled mid-request
                 // Delivery PROGRESS first: it is reported alongside every status, and
@@ -1030,7 +1030,7 @@ export class AccountDialogController {
         try {
             // Claimed WITHOUT planting the bearer — `completeSignIn` installs it only
             // if the user is still waiting for this attempt when the claim returns.
-            claimed = await this.oxyServices.claimSessionByToken(sessionToken, { plantTokens: false });
+            claimed = await this.oxyServices.auth.claimSession(sessionToken, { plantTokens: false });
         }
         catch (error) {
             if (!this.isCurrentAttempt(attempt))
@@ -1095,18 +1095,18 @@ export class AccountDialogController {
     async completeSignIn(attempt, session, user) {
         if (!this.isCurrentAttempt(attempt))
             return;
-        const previousToken = this.oxyServices.getAccessToken();
+        const previousToken = this.oxyServices.session.accessToken;
         try {
             if (session.accessToken)
-                this.oxyServices.setTokens(session.accessToken);
+                this.oxyServices.session.setAccessToken(session.accessToken);
             await this.commitAuthorizedSession(session, user);
         }
         catch (error) {
-            if (session.accessToken && this.oxyServices.getAccessToken() === session.accessToken) {
+            if (session.accessToken && this.oxyServices.session.accessToken === session.accessToken) {
                 if (previousToken)
-                    this.oxyServices.setTokens(previousToken);
+                    this.oxyServices.session.setAccessToken(previousToken);
                 else
-                    this.oxyServices.clearTokens();
+                    this.oxyServices.session.clear();
             }
             throw error;
         }
@@ -1174,7 +1174,7 @@ export class AccountDialogController {
             return;
         let socket;
         try {
-            socket = socketFactory(`${this.oxyServices.getBaseURL()}${AUTH_SESSION_NAMESPACE}`, {
+            socket = socketFactory(`${this.oxyServices.baseURL}${AUTH_SESSION_NAMESPACE}`, {
                 transports: ['websocket'],
                 autoConnect: true,
                 reconnection: true,

package/dist/esm/session/authStateStore.js

@@ -169,8 +169,8 @@ function composeState(durableRaw, warmRaw) {
         // New split layout: the warm key is authoritative for the token fields.
         // Drop anything the durable blob may have carried, then overlay the warm
         // values (a warm key with no token → the session simply has no warm token).
-        delete state.accessToken;
-        delete state.expiresAt;
+        Reflect.deleteProperty(state, 'accessToken');
+        Reflect.deleteProperty(state, 'expiresAt');
         const warm = parseWarmToken(warmRaw);
         if (warm?.accessToken) {
             state.accessToken = warm.accessToken;

package/dist/esm/session/identitySession.js

@@ -94,7 +94,7 @@ export async function establishIdentitySession(args) {
     if (!publicKey) {
         return null;
     }
-    const { challenge } = await oxy.requestChallenge(publicKey, requestOptions);
+    const { challenge } = await oxy.auth.requestChallenge(publicKey, requestOptions);
     const signed = await signChallengeOf(binding)(challenge);
     if (signed.publicKey.toLowerCase() !== publicKey.toLowerCase()) {
         // The signer disagrees with the key we resolved a challenge for — the
@@ -103,11 +103,11 @@ export async function establishIdentitySession(args) {
         throw new Error('Identity sign-in aborted: the signing key does not match the device identity key');
     }
     // `signed.challenge` carries the SIGNATURE (mirrors `signChallengeWithSharedKey`).
-    const session = await oxy.verifyChallenge(signed.publicKey, challenge, signed.challenge, signed.timestamp, binding.deviceName, binding.deviceFingerprint, requestOptions);
+    const session = await oxy.auth.verifyChallenge(signed.publicKey, challenge, signed.challenge, signed.timestamp, binding.deviceName, binding.deviceFingerprint, requestOptions);
     if (!session?.accessToken) {
         return null;
     }
-    // Persist the rotating device credential so later boots re-mint through the
+    // Persist the device credential so later boots re-mint through the
     // fast `POST /session/device/token` lane instead of re-signing a challenge.
     if (session.deviceId && session.deviceSecret) {
         await store.save({

package/dist/esm/session/index.js

@@ -0,0 +1,82 @@
+/**
+ * `@oxy.so/core/session` — the device-first session machinery.
+ *
+ * The multi-account `SessionClient`, the headless account dialog, the persisted
+ * auth-state stores, the token re-mint handler and scheduler, and the cold
+ * boot. `@oxy.so/services` builds `OxyProvider` on it; an app that only calls
+ * the API with a token it already has never needs it.
+ */
+// Session code reaches the identity key (identity-bound sessions), so the
+// crypto shim goes first — see `../crypto/polyfill`.
+import '../crypto/polyfill.js';
+export { DeviceManager } from '../utils/deviceManager.js';
+// ---------------------------------------------------------------------------
+// Session sync (device-scoped multi-account session client)
+// ---------------------------------------------------------------------------
+export { SessionClient } from './SessionClient.js';
+// Shared SessionClient integration layer: the host adapter, the pure
+// DeviceSessionState projection helpers, and the client factory are defined
+// ONCE here so every `@oxy.so/services` platform variant reuses them instead of
+// duplicating a local copy. Each consumer supplies its own `TokenTransport`
+// (native vs. web mint strategies differ) to `createSessionClient`.
+export { createSessionClientHost } from './sessionClientHost.js';
+export { createSessionClient } from './createSessionClient.js';
+export { deviceStateToClientSessions, activeSessionIdOf, activeUserOf, accountIdsOf, } from './projectSessionState.js';
+// Pure projections over the device DIRECTORY (`GET /session/device/directory`,
+// ADR 0002) — the read model that keeps the actor (the human who authenticated)
+// and the subject (the account being acted as) apart. The flat
+// `DeviceSessionState` collapses them into one row, so it can neither tell
+// "signed in as an org" from "a person operating that org" nor hold two people
+// reaching the same org on one device.
+// `canActivateContext` is the switchability question — `available` alone, never
+// composed with `onDevice`, which is a different fact in both directions.
+// `projectDevicePrincipals` is the switcher's shape: people, each with what
+// they may become. Grouped rather than flat because the same organization
+// reached through two people is TWO rows under two humans, which a list keyed
+// by account cannot say.
+export { canActivateContext, directoryDisplayName, directoryHandle, projectDevicePrincipals, resolveActiveContext, resolveDeviceContext, } from './deviceDirectory.js';
+// The switcher's RENDER model over that projection — names, handles and avatar
+// URLs resolved once. Shared by `@oxy.so/services`' account dialog and the
+// auth.oxy.so chooser so the two cannot drift, the same reason the flat
+// projection lived here before it.
+export { buildSwitcherRows, showsPrincipalHeaders } from './deviceSwitcherRows.js';
+// The switch-target predicates over the account GRAPH — a list of accounts to
+// manage, not the device's list of identities to become (that is the directory
+// above). `isSwitchTargetAccount` is the structural half ("is this kind
+// switchable at all?"); `canSwitchIntoAccount` adds the caller's
+// `account:act_as` permission. Exported so the surfaces that render
+// `AccountNode`s — the Console workspace switcher, managed-accounts rows — ask
+// the SAME questions instead of testing a kind literal.
+export { isSwitchTargetAccount, canSwitchIntoAccount, } from './accountSwitchTargets.js';
+// The service/agent counterpart to the human switch predicates above. Kept on
+// its own semantic seam because `bot` is delegable but never human-switchable.
+export { resolveAccountDelegationAccess } from './accountDelegationAccess.js';
+// Headless controller for the unified account dialog. Framework-agnostic
+// state machine + subscribe/getSnapshot store (bind via `useSyncExternalStore`)
+// — sign-in runs through `oxy.auth` (email, password, authenticator, the
+// Commons QR / shared-keychain handoff). Reuses `SessionClient.switchAccount` /
+// `oxy.accounts.actAs` for the uniform switch.
+export { AccountDialogController, createAccountDialogController, } from './accountDialogController.js';
+// ---------------------------------------------------------------------------
+// Device-first session machinery (zero-cookie transport).
+// Persisted auth-state store, the unified re-mint handler + scheduler, and the
+// cold-boot runner. Built ON the `runColdBoot` primitive + `SessionClient`. The
+// device credential is `deviceId` + `deviceSecret`; the access token is re-minted
+// via `POST /session/device/token`.
+// ---------------------------------------------------------------------------
+export { createWebAuthStateStore, createNativeAuthStateStore, createMemoryAuthStateStore, AUTH_STATE_STORAGE_KEY, } from './authStateStore.js';
+// The shared NATIVE DeviceSession credential — how several official apps on one
+// device end up on ONE `DeviceSession` and therefore one active context. It is an
+// ordinary revocable `deviceId` + `deviceSecret`, deliberately NOT the
+// Commons private identity key: an app that only needs a session must never be
+// handed the key that signs identity approvals.
+export { createSharedMirroringAuthStateStore, decideSharedDeviceJoin, decideSharedDevicePublish, normalizeSharedDeviceSessionRead, publishProvenDeviceCredential, readLocalDeviceCredential, } from './sharedDeviceCredential.js';
+// Identity-bound sessions (the identity vault). The pin is the durable
+// `{publicKey, accountId}` binding between this device's PRIMARY identity key
+// and the account it authenticates as; it is what keeps such a client from
+// following the device's mutable `activeAccountId`.
+export { createWebIdentityPinStore, createNativeIdentityPinStore, createMemoryIdentityPinStore, identityPinMatches, IDENTITY_PIN_STORAGE_KEY, } from './identityPin.js';
+export { resolveIdentityPin, establishIdentitySession, } from './identitySession.js';
+export { refreshPersistedSession, refreshDeviceSecretArm, createAuthRefreshHandler, installAuthRefreshHandler, startTokenRefreshScheduler, TOKEN_REFRESH_LEAD_MS, } from './refresh.js';
+export { runSessionColdBoot } from '../boot/sessionColdBoot.js';
+export { runColdBoot } from '../utils/coldBoot.js';