@oxy.so/core 1.18.0 → 3.0.0

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

@@ -0,0 +1,183 @@
+import { OxyServices, type OxyConfig } from '../OxyServices';
+import type { HttpMethod } from '../client/context';
+import type { RequestOptions } from '../HttpService';
+import { type OxyAccountEvent, type OxyAccountEventFeedPage, type OxyMiddleware, type ServiceActingAsVerification, type VerifyAccountEventOptions } from './middleware';
+import { ServerAgencyApi, ServerAssetsApi, ServerLinkedAccountsApi, ServerNotificationsApi, ServerReputationApi } from './namespaces';
+export interface OxyServerConfig extends OxyConfig {
+    /** This service's application credential. Omit to use workload identity (ADR 0026). */
+    serviceAuth?: {
+        apiKey: string;
+        apiSecret: string;
+    };
+    /**
+     * How this backend identifies itself on requests that carry no user session.
+     *
+     * - `'never'` (default): such requests go out anonymous.
+     * - `'when-anonymous'`: they carry this process's service token instead —
+     *   from `serviceAuth`, or, with none, from workload attestation (ADR 0026).
+     *   A user session, when there is one, still wins; `skipAuth` requests stay
+     *   unauthenticated; a process that can produce no service token (a local
+     *   checkout) keeps sending them anonymous.
+     *
+     * Why a server wants it: oxy-api charges anonymous traffic to the SOURCE
+     * ADDRESS (`rl:general`, and a +500 ms `slowDown` per request past 100 in 15
+     * minutes), and a fleet leaves through one NAT address, so every anonymous
+     * read a backend makes shares — and past the threshold pays for — one budget.
+     * A first-party service token is exempt and charged to its own application.
+     * Measured from Mention's task (2026-09-25): `GET /users/:id` 543–575 ms
+     * anonymous past the threshold, `POST /users/by-ids` 19–24 ms with the
+     * service token.
+     */
+    serviceIdentity?: 'never' | 'when-anonymous';
+}
+/**
+ * How long a failed service-token mint sends session-less requests anonymous
+ * before the next attempt, under `serviceIdentity: 'when-anonymous'`.
+ */
+export declare const ANONYMOUS_SERVICE_TOKEN_RETRY_MS = 30000;
+/** `POST /auth/service-token`. */
+export interface ServiceTokenResponse {
+    token: string;
+    expiresIn: number;
+    appName: string;
+}
+/**
+ * Sentinel error raised when a service token is asked for with a known apiKey
+ * but a non-matching secret: credential drift in the caller, or a cross-tenant
+ * cache lookup attempt. Surface as a 401-equivalent.
+ */
+export declare class ServiceCredentialMismatchError extends Error {
+    constructor();
+}
+export declare class OxyServer extends OxyServices {
+    private readonly serviceTokens;
+    private serviceApiKey;
+    private serviceApiSecret;
+    private readonly actingAs;
+    private readonly actingAsPending;
+    /** Public keys only; never private material. */
+    private readonly jwksCache;
+    /**
+     * Before this instant a request without a user session does not try to mint
+     * a service token and goes out anonymous. Set after a failed mint.
+     */
+    private anonymousServiceTokenRetryAt;
+    /**
+     * Express and Socket.IO middleware.
+     *
+     * - `auth(options)` — Express: resolve the caller (user session or service
+     *   token) onto `req.userId` / `req.user` / `req.serviceApp`.
+     * - `socket(options)` — Socket.IO: the same for a handshake.
+     * - `service(options)` — Express: service tokens only.
+     * - `requireScope(scope)` — Express, after `auth`/`service`: the service
+     *   token (and its delegation, if any) must hold `scope`.
+     */
+    readonly middleware: OxyMiddleware;
+    constructor(config: OxyServerConfig);
+    private _serverAssets?;
+    private _serverNotifications?;
+    private _serverLinkedAccounts?;
+    private _serverAgency?;
+    private _serverReputation?;
+    /** Files, plus the service-only metadata and linked-URL lookups. */
+    get assets(): ServerAssetsApi;
+    /** The inbox and push tokens, plus `create`. */
+    get notifications(): ServerNotificationsApi;
+    /** Linked external accounts, plus `forUser`. */
+    get linkedAccounts(): ServerLinkedAccountsApi;
+    /** Delegated capabilities, plus `introspectRequesterAssertion`. */
+    get agency(): ServerAgencyApi;
+    /** Reputation reads, plus `award`. */
+    get reputation(): ServerReputationApi;
+    /**
+     * Set this service's application credential. Each `(apiKey, apiSecret)` pair
+     * is cached independently, so a multi-tenant host switching credentials
+     * cannot leak one tenant's token to another.
+     */
+    configureServiceAuth(apiKey: string, apiSecret: string): void;
+    /**
+     * A service token (short-lived, cached and refreshed per credential pair;
+     * concurrent callers share one mint).
+     *
+     * With no credential configured or passed, the token comes from the process's
+     * attested workload identity (ADR 0026); with neither, this throws.
+     *
+     * If the cache already holds a token for `apiKey` but `apiSecret` does not
+     * constant-time match the secret that produced it, this throws
+     * {@link ServiceCredentialMismatchError} rather than return the cached token.
+     */
+    serviceToken(apiKey?: string, apiSecret?: string): Promise<string>;
+    /**
+     * Forget cached service token(s) so the next `serviceToken()` mints anew —
+     * the way back from a 401 after a credential was revoked or rotated.
+     *
+     * `apiKey` clears that credential's entry; with none, the configured
+     * credential's; with neither, every entry. Synchronous.
+     */
+    invalidateServiceToken(apiKey?: string): void;
+    /**
+     * One request with this service's token. `actAs` sends `X-Oxy-User-Id`: the
+     * request is on behalf of that user (the API checks the delegation grant).
+     * Never cached unless `cache` says so. Rejects with `OxyApiError`.
+     */
+    serviceRequest<T>(method: HttpMethod, url: string, data?: unknown, options?: RequestOptions & {
+        actAs?: string;
+    }): Promise<T>;
+    /**
+     * Whether service app `appId` holds an active delegation grant to act for
+     * `userId`; the grant's scopes, or `null`. Used by `middleware.auth()` for
+     * `X-Oxy-User-Id`.
+     *
+     * Answers are cached per `appId:userId` (a grant for 5 minutes — the
+     * revocation window; a denial or failed lookup for 1 minute), bounded to the
+     * 1000 most recent pairs, and concurrent lookups of one pair share a single
+     * request.
+     */
+    verifyActingAs(appId: string, userId: string): Promise<ServiceActingAsVerification | null>;
+    /**
+     * Account events addressed to this application (Oxy account deletions every
+     * relying application must honour, OxyHQ/Mention#1169).
+     */
+    readonly accountEvents: {
+        /**
+         * Verify an account event token — a webhook body, or a feed entry's `token`
+         * — and return the event. Throws {@link OxyAccountEventError} unless it is
+         * an EdDSA `secevent+jwt` from Oxy's key set, issued by `oxy-auth`,
+         * addressed to this application, carrying exactly one known event. Be
+         * idempotent on `eventId`: Oxy delivers at least once.
+         */
+        verify: (token: string, options?: VerifyAccountEventOptions) => Promise<OxyAccountEvent>;
+        /**
+         * One page of account events for this application, oldest first — the pull
+         * feed behind the webhook. Verify each entry's `token` before acting on it.
+         */
+        list: (options?: {
+            after?: string;
+            limit?: number;
+        }) => Promise<OxyAccountEventFeedPage>;
+    };
+    /**
+     * The bearer for a request with no user session, under `serviceIdentity:
+     * 'when-anonymous'`: this process's service token, or `null` to send the
+     * request anonymous.
+     *
+     * `null`, never a throw, whenever there is no token to offer:
+     * - no key pair and no attestable workload (a local checkout);
+     * - the mint failed. The request still goes out, anonymous, and so does every
+     *   request for the next {@link ANONYMOUS_SERVICE_TOKEN_RETRY_MS}, so an Oxy
+     *   refusing attestation is asked once per window rather than once per read.
+     *
+     * The token comes from {@link serviceToken}: cached and single-flight, so
+     * concurrent reads share one mint.
+     */
+    private serviceTokenForAnonymousRequest;
+    private canMintServiceToken;
+    private mintServiceToken;
+    /** A token obtained by attestation, cached like a credential's (one identity per process). */
+    private workloadServiceToken;
+    private lookupActingAs;
+    private rememberActingAs;
+    private verifyAccountEvent;
+    /** The `appId` claim of this service's own token. */
+    private configuredServiceAppId;
+}

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

@@ -1,6 +1,5 @@
 import type { NextFunction, Request, RequestHandler, Response } from 'express';
-import type { OxyServices } from '../OxyServices';
-import type { OxyAuthRefusal } from '../mixins/OxyServices.utility';
+import type { AuthMiddlewareOptions, OxyAuthRefusal, OxyMiddleware } from './middleware';
 import { OXY_SERVICE_ENVIRONMENTS, type OxyServiceEnvironment } from '../utils/oxyServiceEnvironment';
 export { OXY_SERVICE_ENVIRONMENTS };
 export type { OxyServiceEnvironment, OxyAuthRefusal };
@@ -51,11 +50,11 @@ export interface OxyAuthenticatedRequest extends OxyAuthRequest {
 }
 export interface OxyAuthMiddlewareOptions {
     /**
-     * Options forwarded to `oxy.auth()`.
+     * Options forwarded to `server.middleware.auth()`.
      * `optional` is forced to `true` by the composed helpers so route guards can
      * produce one consistent 401 shape.
      */
-    auth?: Parameters<OxyServices['auth']>[0];
+    auth?: AuthMiddlewareOptions;
 }
 export declare function getOxyUserId(req: Request): string | null;
 export declare function isOxyAuthenticated(req: Request): req is OxyAuthenticatedRequest;
@@ -138,7 +137,7 @@ export declare function getRequiredOxyUserId(req: Request): string;
  * Why the credential on this request was refused, or `null` when none was
  * presented (or it was accepted).
  *
- * Set by `oxy.auth()` — including the `optional: true` mount the composed
+ * Set by `server.middleware.auth()` — including the `optional: true` mount the composed
  * helpers use, where a refusal otherwise leaves no trace: the request simply
  * arrives unauthenticated and the host answers its own generic 401. Hosts log
  * this beside their own 401; it is diagnostic and **must not be put into a
@@ -146,5 +145,9 @@ export declare function getRequiredOxyUserId(req: Request): string;
  */
 export declare function getOxyAuthRefusal(req: Request): OxyAuthRefusal | null;
 export declare function requireOxyAuth(req: Request, res: Response, next: NextFunction): void;
-export declare function createOptionalOxyAuth(oxy: OxyServices, options?: OxyAuthMiddlewareOptions): RequestHandler;
-export declare function createOxyAuthMiddleware(oxy: OxyServices, options?: OxyAuthMiddlewareOptions): RequestHandler;
+/** What the composed helpers need of an `OxyServer`: its `middleware.auth`. */
+export interface OxyAuthHost {
+    readonly middleware: Pick<OxyMiddleware, 'auth'>;
+}
+export declare function createOptionalOxyAuth(oxy: OxyAuthHost, options?: OxyAuthMiddlewareOptions): RequestHandler;
+export declare function createOxyAuthMiddleware(oxy: OxyAuthHost, options?: OxyAuthMiddlewareOptions): RequestHandler;

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

@@ -6,15 +6,21 @@
  *
  * @example
  * ```ts
- * import { createOxyRateLimit } from '@oxy.so/core/server';
- * import { oxyClient } from '@oxy.so/core';
+ * import { OxyServer, createOxyAuthMiddleware, createOxyRateLimit } from '@oxy.so/core/server';
  *
- * const oxy = oxyClient({ apiUrl: 'https://api.oxy.so' });
+ * const oxy = new OxyServer({ baseURL: 'https://api.oxy.so', serviceAuth: { apiKey, apiSecret } });
  *
  * app.use(createOxyRateLimit(oxy, { store: redisStore }));
+ * app.use('/api', createOxyAuthMiddleware(oxy));
  * ```
  */
+export { OxyServer, ServiceCredentialMismatchError, ANONYMOUS_SERVICE_TOKEN_RETRY_MS } from './OxyServer';
+export type { OxyServerConfig, ServiceTokenResponse } from './OxyServer';
+export { ServerAgencyApi, ServerAssetsApi, ServerLinkedAccountsApi, ServerNotificationsApi, ServerReputationApi, } from './namespaces';
+export { OxyAccountEventError, OXY_ACCOUNT_DELETED_EVENT_URI } from './middleware';
+export type { AuthMiddlewareOptions, OxyAccountEvent, OxyAccountEventFeedItem, OxyAccountEventFeedPage, OxyMiddleware, ServiceActingAsVerification, ServiceApp, VerifyAccountEventOptions, } from './middleware';
 export { createOptionalOxyAuth, createOxyAuthMiddleware, getOxyAuthRefusal, getOxyBillingPrincipal, getOxyDelegatedUserId, getOxyRequestAttribution, getOxyUserId, getRequiredOxyBillingPrincipal, getRequiredOxyUserId, isOxyAuthenticated, requireOxyAuth, OXY_SERVICE_ENVIRONMENTS, } from './auth';
+export type { OxyAuthHost } from './auth';
 export type { OxyAuthenticatedRequest, OxyAuthRefusal, OxyAuthMiddlewareOptions, OxyAuthRequest, OxyBillingPrincipal, OxyRequestAttribution, OxyRequestUser, OxyServiceActingAsContext, OxyServiceAppContext, OxyServiceEnvironment, } from './auth';
 export { createOxyRateLimit } from './rateLimit';
 export type { OxyRateLimitOptions } from './rateLimit';
@@ -34,7 +40,7 @@ export type { OxyInvalidationPublisher, OxyUserInvalidationHandlerOptions, } fro
 export { evictOxyIdentityCache, oxyUserByIdCacheKey, OXY_IDENTITY_CACHE_PREFIXES } from '../utils/identityCacheSweep';
 export type { OxyIdentityCacheEvictor } from '../utils/identityCacheSweep';
 export { registrableApex } from '../utils/registrableApex';
-export { isOfficialWebOrigin } from '../utils/officialOrigins';
+export { isLoopbackOrigin, isOfficialWebOrigin, isAllowedDeviceJoinOrigin } from '../utils/officialOrigins';
 export { createEcosystemTraffic } from './traffic';
 export type { EcosystemTrafficOptions } from './traffic';
 export { observeNodeHttp, withoutNodeHttpObservation } from './trafficNodeHttp';

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

@@ -0,0 +1,291 @@
+import type { ApiError, User } from '../models/interfaces';
+import { type OxyServiceEnvironment } from '../utils/oxyServiceEnvironment';
+/**
+ * Result from the service-acting-as verification endpoint.
+ * Confirms that a given service app holds an active delegation grant for
+ * the supplied user, along with the explicit scope list the grant covers.
+ *
+ * The API side stores this as an ordinary `app_grants` row — the SAME revocable
+ * record the OAuth consent screen writes and the "Connected apps" UI lists and
+ * deletes — whose `scopes` name `acting-as:offline`. There is deliberately no
+ * separate delegation table: a second store would be a second revocation
+ * surface, and a user who disconnects an application in "Connected apps" means
+ * it, so one revoke has to end everything.
+ *
+ * `scopes` is what THAT USER consented to, not what the application may do in
+ * general. `requireScope` intersects it with the token's own app-wide scopes for
+ * a delegated request, and the intersection is the effective authority.
+ *
+ * The SDK never inspects the grant directly — it round-trips through
+ * `GET /internal/service-acting-as/verify?appId=...&userId=...` so the
+ * authoritative store stays server-side.
+ */
+export interface ServiceActingAsVerification {
+    authorized: boolean;
+    scopes: string[];
+}
+/** The SET `events` member Oxy uses for an account deletion. */
+export declare const OXY_ACCOUNT_DELETED_EVENT_URI = "https://oxy.so/events/account.deleted";
+/**
+ * A verified account event from Oxy (OxyHQ/Mention#1169): a person deleted
+ * their Oxy account and every relying application must erase what it holds
+ * for them. Returned by `verifyAccountEvent` only after the signature, `typ`,
+ * issuer and audience all check out.
+ */
+export interface OxyAccountEvent {
+    /** The event id (`jti`). Stable across webhook retries and the pull feed: dedupe on it. */
+    eventId: string;
+    type: 'account.deleted';
+    /** The deleted Oxy account. */
+    userId: string;
+    /**
+     * The account's handle at deletion time, for relying parties that address
+     * the person by handle (an ActivityPub actor URI). `null` when the account had
+     * none, or when the token predates the field.
+     */
+    username: string | null;
+    /** ISO-8601 time the deletion committed. */
+    occurredAt: string;
+    /** `true` when Oxy archived the row to keep financial records. Erase either way. */
+    retained: boolean;
+    /** The application the event was addressed to (`aud`). */
+    applicationId: string;
+    /** Seconds since the epoch the token was issued at (`iat`). */
+    issuedAt: number;
+}
+/** One entry of the account-event pull feed (`GET /account-events`). */
+export interface OxyAccountEventFeedItem {
+    eventId: string;
+    type: 'account.deleted';
+    userId: string;
+    username: string | null;
+    occurredAt: string;
+    retained: boolean;
+    /** The same signed token the webhook carries. Verify it with `verifyAccountEvent`. */
+    token: string;
+}
+export interface OxyAccountEventFeedPage {
+    events: OxyAccountEventFeedItem[];
+    /** Pass back as `after` to continue; unchanged when the page is empty. */
+    nextCursor: string | null;
+}
+export interface VerifyAccountEventOptions {
+    /**
+     * The application id the token must be addressed to. Defaults to the `appId`
+     * of this client's configured service credential.
+     */
+    audience?: string;
+    /** Defaults to `/.well-known/jwks.json` on this client's API origin. */
+    jwksUrl?: string;
+}
+/** Why an account event token was refused. `message` never contains the token. */
+export declare class OxyAccountEventError extends Error {
+    constructor(message: string);
+}
+/**
+ * Service app metadata attached to requests authenticated with service tokens.
+ *
+ * Every field comes from the token's SIGNED payload and is populated only after
+ * the signature, `iss`/`aud`/`type` binding and expiry all pass — so a verifier
+ * holding this object can name the responsible principals without a lookup of
+ * its own. Together with `credentialId` and `ownerAccountId` it is the canonical
+ * attribution tuple of ADR 0007 minus the delegated user.
+ *
+ * `scopes` are the EFFECTIVE scopes: the credential's own scopes intersected
+ * with the owning application's grant at mint time (the API's `intersectScopes`
+ * is the single authority for that intersection — nothing re-intersects here).
+ * Route-level checks narrow further via `requireScope()`.
+ *
+ * A delegated end user is NOT a field of this type, and must never become one.
+ * It lives in `req.serviceActingAs` / `req.userId`, is authorised per request,
+ * and is attribution only.
+ */
+export interface ServiceApp {
+    appId: string;
+    appName: string;
+    scopes: string[];
+    /**
+     * `internal` when the caller is one of Oxy's own applications: app to app it
+     * is trusted outright — {@link requireScope} passes and it may act for a user
+     * without a delegation grant. `external` keeps every scope and grant rule.
+     * What the USER may do (their accounts, plan, limits) is still for the
+     * receiving service to decide. A token without the claim reads as `external`.
+     */
+    tier: 'internal' | 'external';
+    /** The credentialId of the specific service credential that minted this token. */
+    credentialId: string;
+    /**
+     * The Oxy account that owns `appId` and is financially responsible for it.
+     * The BILLING principal — never a user id, and never the delegated
+     * `X-Oxy-User-Id` (ADR 0007).
+     */
+    ownerAccountId: string;
+    /** Test/live isolation (F2.0): which `ApplicationCredential.environment` minted this token. */
+    environment: OxyServiceEnvironment;
+}
+/**
+ * Why a request's credential was refused, recorded on the request itself.
+ *
+ * The middleware answers a fixed, deliberately uninformative body to the
+ * client; this is the other half of that trade. A refusal is ALWAYS observable
+ * to the HOST: it is logged at `warn` with a stable `code`, handed to
+ * `onRefusal`, and left on `req.oxyAuthRefusal` for the host's own logs.
+ *
+ * It exists because the opposite cost was measured: Oxy served
+ * `{"keys":[]}` from `/.well-known/jwks.json` with no Ed25519 signing key
+ * bound, every service token failed `Oxy service-token key set is unavailable`,
+ * and on the OPTIONAL path that failure fell straight through to `next()`.
+ * The host then answered its own generic 401 and logged nothing at all, so the
+ * one fact that named the fault — an empty key set — existed nowhere. Hours.
+ *
+ * **Nothing here is ever sent to a client, and `reason` never contains the
+ * token, a signature, a secret or a session id.** It carries the SDK's own
+ * failure message (`kid` unknown, audience mismatch, key set unavailable) plus
+ * the ids already considered safe to log elsewhere in this middleware.
+ */
+export interface OxyAuthRefusal {
+    /** Stable, greppable code. Matches the `code` a non-optional refusal answers. */
+    code: string;
+    /** Which credential lane refused. */
+    stage: 'token' | 'service-token' | 'session';
+    /** Human-readable cause. Never a token, signature, secret or session id. */
+    reason: string;
+    /** The status a NON-optional mount would have answered with. */
+    status: number;
+    /**
+     * `true` when the middleware was mounted with `optional: true`, so this
+     * refusal did not produce a response — the request continued unauthenticated
+     * and whatever the host does next (typically its own generic 401) is the
+     * only thing the client sees.
+     */
+    optional: boolean;
+}
+/**
+ * Expected JWT issuer for tokens issued by the Oxy auth service.
+ */
+export declare const OXY_JWT_ISSUER = "oxy-auth";
+/**
+ * Options for `server.middleware.auth()`.
+ */
+export interface AuthMiddlewareOptions {
+    /** Enable debug logging (default: false) */
+    debug?: boolean;
+    /** Custom error handler - receives error object, can return response */
+    onError?: (error: ApiError) => unknown;
+    /** Load full user profile from API (default: false for performance) */
+    loadUser?: boolean;
+    /** Optional auth - attach user if token present but don't block (default: false) */
+    optional?: boolean;
+    /**
+     * Called whenever a PRESENTED credential is refused, on the optional path as
+     * well as the blocking one. Runs before the response (if any) and after
+     * `req.oxyAuthRefusal` is set, so a host can raise its own alert or carry the
+     * code into its request log. Throwing from it is swallowed — an observer must
+     * not be able to turn a refusal into a 500.
+     *
+     * Refusal is about a credential that was offered and rejected: a request with
+     * NO `Authorization` header is not refused and does not reach this.
+     */
+    onRefusal?: (refusal: OxyAuthRefusal) => void;
+    /**
+     * Public JWKS endpoint used for Ed25519 service-token verification. Defaults
+     * to `/.well-known/jwks.json` on this Oxy client's configured API origin.
+     */
+    serviceTokenJwksUrl?: string;
+    /**
+     * Expected JWT issuer. Defaults to `'oxy-auth'`. Override only if you run
+     * a private fork of the Oxy auth server under a different `iss` claim.
+     */
+    expectedIssuer?: string;
+    /**
+     * Expected JWT audience. Defaults to `'oxy-api'`. Override only if your
+     * private fork mints tokens for a different audience.
+     */
+    expectedAudience?: string;
+}
+/**
+ * What the middleware needs from the server it is mounted on. `OxyServer`
+ * builds it; every member is resolved at call time, so a test can spy on the
+ * server's own methods.
+ */
+export interface OxyMiddlewareHost {
+    readonly baseURL: string;
+    readonly jwksCache: ServiceTokenJwksCache;
+    validateSession(sessionId: string, options?: {
+        deviceFingerprint?: string;
+        useHeaderValidation?: boolean;
+    }): Promise<{
+        valid: boolean;
+        user?: User;
+    } | null>;
+    verifyActingAs(appId: string, userId: string): Promise<ServiceActingAsVerification | null>;
+}
+/** Build the middleware set for one server. See `OxyServer.middleware`. */
+export declare function createOxyMiddleware(host: OxyMiddlewareHost): {
+    auth: (options?: AuthMiddlewareOptions) => (req: AuthReq, res: AuthRes, next: AuthNext) => Promise<unknown>;
+    socket: (options?: {
+        debug?: boolean;
+    }) => (socket: SocketLike, next: (err?: Error) => void) => Promise<void>;
+    service: (options?: {
+        debug?: boolean;
+        /** Observe refusals on the service lane; forwarded straight to `auth()`. */
+        onRefusal?: (refusal: OxyAuthRefusal) => void;
+        serviceTokenJwksUrl?: string;
+        expectedIssuer?: string;
+        expectedAudience?: string;
+    }) => (req: AuthReq, res: AuthRes, next: AuthNext) => Promise<void>;
+    requireScope: (scope: string) => (req: AuthReq, res: AuthRes, next: AuthNext) => void;
+};
+/** The middleware set `OxyServer.middleware` exposes. */
+export type OxyMiddleware = ReturnType<typeof createOxyMiddleware>;
+export interface ServiceTokenPublicJwk {
+    readonly kty: 'OKP';
+    readonly crv: 'Ed25519';
+    readonly x: string;
+    readonly use: 'sig';
+    readonly alg: 'EdDSA';
+    readonly kid: string;
+}
+export interface ServiceTokenJwksCache {
+    keys: Map<string, ServiceTokenPublicJwk>;
+    expiresAt: number;
+    lastAttemptAt: number;
+    pending?: Promise<void>;
+}
+export declare function parseJsonSegment(segment: string): Record<string, unknown>;
+export declare function resolveServiceTokenPublicKey(kid: string, url: string, cache: ServiceTokenJwksCache): Promise<ServiceTokenPublicJwk>;
+interface AuthReq {
+    method?: string;
+    path?: string;
+    headers: Record<string, string | string[] | undefined>;
+    query?: Record<string, unknown>;
+    userId?: string | null;
+    user?: User | null;
+    accessToken?: string;
+    sessionId?: string | null;
+    serviceApp?: ServiceApp;
+    serviceActingAs?: {
+        userId: string;
+        scopes: string[];
+    };
+    oxyAuthRefusal?: OxyAuthRefusal;
+}
+interface AuthRes {
+    status(code: number): AuthRes;
+    json(body: unknown): unknown;
+}
+type AuthNext = (err?: unknown) => void;
+interface SocketLike {
+    handshake?: {
+        auth?: {
+            token?: string;
+        };
+    };
+    data?: Record<string, unknown>;
+    user?: {
+        id: string;
+        userId: string;
+        sessionId?: string | null;
+    };
+}
+export {};

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

@@ -0,0 +1,98 @@
+/**
+ * The server-side halves of the namespaces: what exists only with a service
+ * credential. `OxyServer` returns these from its namespace getters, so
+ * `server.assets.metadataByIds(...)` sits beside every client method of
+ * `oxy.assets`.
+ */
+import type { CreateOxyNotificationRequest, AwardReputationInput, ReputationTransaction, ServiceLinkedAccountListResponse } from '@oxy.so/contracts';
+import type { Notification, ServiceAssetMetadata, ServiceAssetMetadataBySha, ServiceLinkedDownloadUrl } from '../models/interfaces';
+import { AssetsApi } from '../api/assets';
+import { NotificationsApi } from '../api/notifications';
+import { LinkedAccountsApi } from '../api/linkedAccounts';
+import { AgencyApi, type RequesterAssertionGrant, type RequesterAssertionIntrospection } from '../api/agency';
+import { ReputationApi } from '../api/reputation';
+export declare 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.
+     */
+    metadataByIds(ids: string[], options?: {
+        partial?: boolean;
+    }): Promise<ServiceAssetMetadata[]>;
+    /**
+     * 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.
+     */
+    linkedDownloadUrls(ids: string[]): Promise<ServiceLinkedDownloadUrl[]>;
+    /**
+     * 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.
+     */
+    metadataBySha256(sha256s: string[]): Promise<ServiceAssetMetadataBySha[]>;
+}
+export declare 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.
+     */
+    create(data: CreateOxyNotificationRequest): Promise<Notification>;
+}
+export declare 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`.
+     */
+    forUser(userId: string): Promise<ServiceLinkedAccountListResponse>;
+}
+export declare 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.
+     */
+    mintRequesterAssertion(input: {
+        agentId: string;
+        subjectToken: string;
+    }): Promise<RequesterAssertionGrant>;
+    /**
+     * 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.
+     */
+    introspectRequesterAssertion(input: {
+        assertion: string;
+        presenter: {
+            applicationId: string;
+            credentialId: string;
+        };
+    }): Promise<RequesterAssertionIntrospection>;
+}
+export declare 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.
+     */
+    award(input: AwardReputationInput): Promise<ReputationTransaction>;
+}