@oxy.so/core 1.3.1 → 1.5.0

package/dist/types/index.d.ts

@@ -28,7 +28,7 @@ export type { CommonsDeliveryFacts, CommonsDeliveryPlatform, CommonsDeliveryRout
 export type { ServiceTokenResponse, OAuthUserInfoResponse, OAuthTokenExchangeResult, } 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 { ServiceApp, ServiceActingAsVerification, OxyAuthRefusal } from './mixins/OxyServices.utility';
 export type { ContactDiscoveryMatch, ContactDiscoveryResponse, } from './mixins/OxyServices.contacts';
 export type { InitDeviceTransferResult, DeviceTransferOutcome, } from './mixins/OxyServices.deviceTransfer';
 export type { BulkFollowEntry, BulkFollowResult, BulkUnfollowEntry, BulkUnfollowResult, FollowMutationResult, ViewerGraph, } from './mixins/OxyServices.user';
@@ -39,7 +39,7 @@ export type { CanonicalUserHandleInput, UserHandleInput } from './utils/userHand
 export { normalizeProfileLinks } from './utils/profileLinks';
 export type { ProfileLink, ProfileLinkMetadata } from './utils/profileLinks';
 export type { PublicApplication, ConnectedApp, ConnectedMcpClient, } from './mixins/OxyServices.connectedApps';
-export type { AccountCapabilityPolicy, AvailableCapabilityCatalog, CapabilityExecutionAuthorization, CreateDelegationGrantInput, DelegationCatalogBinding, DelegationGrantView, PutAccountCapabilityPolicyInput, UpdateDelegationGrantInput, } from './mixins/OxyServices.agency';
+export type { AccountCapabilityPolicy, AvailableCapabilityCatalog, CapabilityExecutionAuthorization, CreateDelegationGrantInput, DelegationCatalogBinding, DelegationGrantView, PutAccountCapabilityPolicyInput, RequesterAssertionGrant, RequesterAssertionIntrospection, UpdateDelegationGrantInput, } from './mixins/OxyServices.agency';
 export type { StoreCategory, StoreRating, StoreListingSummary, StoreListingDetail, StoreScreenshot, StoreScreenshotPlatform, StoreReview, StoreOwnReview, WriteStoreReviewInput, StoreListingStatus, PublisherListing, WriteListingInput, AddScreenshotInput, UpdateScreenshotInput, StorePage, StorePageOptions, StoreReviewsOptions, } from './mixins/OxyServices.store';
 export type { AccountKind, AccountCategoryId, AccountRelationship, AccountRole, AccountMemberStatus, AccountMemberSource, AccountMember, AccountNode, ListAccountsOptions, CreateAccountInput, UpdateAccountInput, ProvisionChannelInput, ProvisionChannelMemberInput, ProvisionChannelResult, InviteAccountMemberInput, UpdateAccountMemberInput, TransferAccountOwnershipInput, AccountSuccessResult, SwitchAccountResult, Application, ApplicationType, ApplicationStatus, ApplicationCredential, ApplicationCredentialType, ApplicationCredentialStatus, ApplicationEnvironment, CreateApplicationInput, UpdateApplicationInput, CreateApplicationCredentialInput, RotateApplicationCredentialInput, ApplicationCredentialWithSecret, RotateApplicationCredentialResult, ApplicationUsagePeriod, ApplicationUsageSummary, ApplicationUsageByDay, ApplicationUsageByEndpoint, ApplicationUsageStats, } from './mixins/OxyServices.accounts';
 export { ACCOUNT_CATEGORY_IDS, MAX_ACCOUNT_CATEGORIES, SELECTABLE_ACCOUNT_CATEGORY_IDS, isSelectableAccountCategoryId, kindAcceptsAccountCategories, } from './mixins/OxyServices.accounts';

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

@@ -69,6 +69,23 @@ export interface CapabilityExecutionAuthorization {
     createdAt: string;
     updatedAt: string;
 }
+/** A present-requester assertion minted for a product backend (ADR 0025). */
+export interface RequesterAssertionGrant {
+    assertion: string;
+    expiresAt: string;
+    requesterAccountId: string;
+    agentId: string;
+}
+/** Oxy's live answer to the audience that consumed an assertion (ADR 0025). */
+export interface RequesterAssertionIntrospection {
+    active: boolean;
+    requesterAccountId?: string;
+    agentId?: string;
+    applicationId?: string;
+    credentialId?: string;
+    jti?: string;
+    expiresAt?: string;
+}
 export declare function OxyServicesAgencyMixin<T extends typeof OxyServicesBase>(Base: T): {
     new (...args: any[]): {
         listAvailableCapabilityCatalogs(accountId: string): Promise<AvailableCapabilityCatalog[]>;
@@ -82,6 +99,30 @@ export declare function OxyServicesAgencyMixin<T extends typeof OxyServicesBase>
         listCapabilityExecutionAuthorizations(ownerAccountId: string): Promise<CapabilityExecutionAuthorization[]>;
         revokeCapabilityExecutionAuthorization(authorizationId: string, ownerAccountId: string): Promise<void>;
         listCapabilityAuditEvents(accountId: string): Promise<AuditEvent[]>;
+        /**
+         * Product backend → Oxy: trade the signed-in requester's access token for a
+         * one-use assertion naming `agentId` (ADR 0025). Authenticated with THIS
+         * instance's service credential (`configureServiceAuth`). `subjectToken` is
+         * sent 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 an assertion. 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>;
         httpService: import("../HttpService").HttpService;
         cloudURL: string;
         config: import("../OxyServices.base").OxyConfig;

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

@@ -58,6 +58,43 @@ export interface ServiceApp {
     /** 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;
+}
 /**
  * Options for oxyClient.auth() middleware
  */
@@ -70,6 +107,17 @@ interface AuthMiddlewareOptions {
     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.
@@ -362,6 +410,7 @@ interface AuthReq {
         userId: string;
         scopes: string[];
     };
+    oxyAuthRefusal?: OxyAuthRefusal;
 }
 interface AuthRes {
     status(code: number): AuthRes;

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

@@ -1,8 +1,9 @@
 import type { NextFunction, Request, RequestHandler, Response } from 'express';
 import type { OxyServices } from '../OxyServices';
+import type { OxyAuthRefusal } from '../mixins/OxyServices.utility';
 import { OXY_SERVICE_ENVIRONMENTS, type OxyServiceEnvironment } from '../utils/oxyServiceEnvironment';
 export { OXY_SERVICE_ENVIRONMENTS };
-export type { OxyServiceEnvironment };
+export type { OxyServiceEnvironment, OxyAuthRefusal };
 export interface OxyRequestUser {
     id: string;
     _id?: string;
@@ -35,6 +36,12 @@ export interface OxyAuthRequest extends Request {
     sessionId?: string | null;
     serviceApp?: OxyServiceAppContext;
     serviceActingAs?: OxyServiceActingAsContext;
+    /**
+     * Why the presented credential was refused, when one was and the request
+     * still reached the handler (the optional path). Read it with
+     * {@link getOxyAuthRefusal} — never put it in a response body.
+     */
+    oxyAuthRefusal?: OxyAuthRefusal;
 }
 export interface OxyAuthenticatedRequest extends OxyAuthRequest {
     userId: string;
@@ -125,6 +132,17 @@ export declare function getOxyDelegatedUserId(req: Request): string | null;
  */
 export declare function getOxyRequestAttribution(req: Request): OxyRequestAttribution | null;
 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
+ * 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
+ * response body**, which is exactly what it is kept out of.
+ */
+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;

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

@@ -14,8 +14,8 @@
  * app.use(createOxyRateLimit(oxy, { store: redisStore }));
  * ```
  */
-export { createOptionalOxyAuth, createOxyAuthMiddleware, getOxyBillingPrincipal, getOxyDelegatedUserId, getOxyRequestAttribution, getOxyUserId, getRequiredOxyBillingPrincipal, getRequiredOxyUserId, isOxyAuthenticated, requireOxyAuth, OXY_SERVICE_ENVIRONMENTS, } from './auth';
-export type { OxyAuthenticatedRequest, OxyAuthMiddlewareOptions, OxyAuthRequest, OxyBillingPrincipal, OxyRequestAttribution, OxyRequestUser, OxyServiceActingAsContext, OxyServiceAppContext, OxyServiceEnvironment, } from './auth';
+export { createOptionalOxyAuth, createOxyAuthMiddleware, getOxyAuthRefusal, getOxyBillingPrincipal, getOxyDelegatedUserId, getOxyRequestAttribution, getOxyUserId, getRequiredOxyBillingPrincipal, getRequiredOxyUserId, isOxyAuthenticated, requireOxyAuth, OXY_SERVICE_ENVIRONMENTS, } 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';
 export { assertSafePublicUrl, isBlockedIp, safeFetch, SsrfRejection, UpstreamError, ALLOWED_PORTS, ALLOWED_PROTOCOLS, BLOCKED_HOSTNAMES, DEFAULT_USER_AGENT, MAX_REDIRECTS, MAX_URL_LENGTH, UPSTREAM_HEADERS_TIMEOUT_MS, } from './safeFetch';
@@ -26,6 +26,8 @@ export { buildOxyCspDirectives, buildOxyPagesHeaders, createOxySecurityHeaders,
 export type { OxyCspDirective, OxyCspExtensions, OxyPagesHeadersOptions, OxySecurityHeadersOptions, } from './securityHeaders';
 export { CapabilityTicketError, createCapabilityTicketMiddleware, inputSatisfiesCapabilityLimits, issueCapabilityTicket, readCapabilityAuthorization, verifyCapabilityTicket, } from './capabilityTicket';
 export type { CapabilityTicketMiddlewareOptions, CapabilityTicketRequest, CapabilityTicketSigningOptions, CapabilityTicketVerificationOptions, } from './capabilityTicket';
+export { createOxyJwksKeyResolver, createOxyRequesterAssertionAuth, OXY_REQUESTER_ASSERTION_DEFAULT_ISSUER, OXY_REQUESTER_ASSERTION_HEADER, OXY_REQUESTER_ASSERTION_MAX_TTL_SECONDS, OXY_REQUESTER_ASSERTION_TYPE, OxyRequesterAssertionError, oxyRequesterAssertionClaimsSchema, readOxyRequesterAssertionKeyId, signOxyRequesterAssertion, verifyOxyRequesterAssertion, } from './requesterAssertion';
+export type { OxyJwksKeyResolverOptions, OxyRequesterAssertionAuthOptions, OxyRequesterAssertionClaims, OxyRequesterAssertionErrorCode, OxyRequesterAssertionIntrospection, OxyRequesterAssertionIntrospector, OxyRequesterAssertionRequest, OxyRequesterAssertionVerificationOptions, OxyRequesterContext, } from './requesterAssertion';
 export { verifySecret } from './verifySecret';
 export { createOxyUserInvalidationHandler, publishOxyUserInvalidation, } from './userInvalidation';
 export type { OxyInvalidationPublisher, OxyUserInvalidationHandlerOptions, } from './userInvalidation';

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

@@ -0,0 +1,151 @@
+/**
+ * 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,
+ * 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`
+ * and gets `req.userId` from the verified, introspected and consumed assertion.
+ *
+ * Signing and stateless verification live here so Oxy (the signer) and every
+ * verifier share one implementation of the format.
+ */
+import { type KeyObject } from 'node:crypto';
+import type { RequestHandler } from 'express';
+import { z } from 'zod';
+import type { OxyAuthRequest } from './auth';
+export declare const OXY_REQUESTER_ASSERTION_TYPE = "OXY-REQUESTER+JWT";
+/** The request header an audience reads the assertion from. */
+export declare const OXY_REQUESTER_ASSERTION_HEADER = "x-oxy-requester-assertion";
+/** Oxy signs for 120 s; no verifier accepts a lifetime above this ceiling. */
+export declare const OXY_REQUESTER_ASSERTION_MAX_TTL_SECONDS = 300;
+export declare const OXY_REQUESTER_ASSERTION_DEFAULT_ISSUER = "https://api.oxy.so";
+export declare const oxyRequesterAssertionClaimsSchema: z.ZodObject<{
+    iss: z.ZodString;
+    aud: z.ZodString;
+    /** The requester account. */
+    sub: z.ZodString;
+    jti: z.ZodString;
+    iat: z.ZodNumber;
+    exp: z.ZodNumber;
+    /** The application the assertion was minted for, and the only valid presenter. */
+    azp: z.ZodString;
+    /** The exact credential of that application. */
+    cid: z.ZodString;
+    /** The one native agent this requester may reach with it. */
+    agentId: z.ZodString;
+}, "strict", z.ZodTypeAny, {
+    exp: number;
+    sub: string;
+    aud: string;
+    iss: string;
+    iat: number;
+    jti: string;
+    azp: string;
+    cid: string;
+    agentId: string;
+}, {
+    exp: number;
+    sub: string;
+    aud: string;
+    iss: string;
+    iat: number;
+    jti: string;
+    azp: string;
+    cid: string;
+    agentId: string;
+}>;
+export type OxyRequesterAssertionClaims = z.infer<typeof oxyRequesterAssertionClaimsSchema>;
+export type OxyRequesterAssertionErrorCode = 'malformed' | 'unknown_key' | 'invalid_signature' | 'invalid_claims' | 'wrong_issuer' | 'wrong_audience' | 'not_yet_valid' | 'expired' | 'ttl_exceeded';
+export declare class OxyRequesterAssertionError extends Error {
+    readonly code: OxyRequesterAssertionErrorCode;
+    constructor(code: OxyRequesterAssertionErrorCode);
+}
+/** Signs an assertion. Oxy is the only intended caller. */
+export declare function signOxyRequesterAssertion(claims: OxyRequesterAssertionClaims, signing: {
+    readonly keyId: string;
+    readonly privateKey: KeyObject;
+}): string;
+/** Reads the `kid` without trusting anything else in the token. */
+export declare function readOxyRequesterAssertionKeyId(token: string): string;
+export interface OxyRequesterAssertionVerificationOptions {
+    readonly publicKey: KeyObject | undefined;
+    readonly issuer: string;
+    readonly audience: string;
+    readonly now?: Date;
+}
+/**
+ * Stateless verification: header, signature, claim shape, issuer, audience and
+ * lifetime. It does NOT prove the assertion is unused or that the requester's
+ * session is still live — only introspection does.
+ */
+export declare function verifyOxyRequesterAssertion(token: string, options: OxyRequesterAssertionVerificationOptions): OxyRequesterAssertionClaims;
+export interface OxyJwksKeyResolverOptions {
+    readonly jwksUrl: string;
+    readonly fetch?: typeof fetch;
+    readonly clock?: () => number;
+}
+/**
+ * Cached Ed25519 JWKS resolver. An unknown `kid` refreshes at most once a
+ * minute, so a flood of forged key ids cannot turn into a flood of fetches. A
+ * failed refresh keeps serving keys that are still inside their cache window.
+ */
+export declare function createOxyJwksKeyResolver(options: OxyJwksKeyResolverOptions): (keyId: string) => Promise<KeyObject | undefined>;
+export interface OxyRequesterAssertionIntrospection {
+    readonly active: boolean;
+    readonly requesterAccountId?: string;
+    readonly agentId?: string;
+    readonly applicationId?: string;
+    readonly credentialId?: string;
+    readonly jti?: string;
+    readonly expiresAt?: string;
+}
+export interface OxyRequesterAssertionIntrospector {
+    introspectRequesterAssertion(input: {
+        assertion: string;
+        presenter: {
+            applicationId: string;
+            credentialId: string;
+        };
+    }): Promise<OxyRequesterAssertionIntrospection>;
+    getBaseURL(): string;
+}
+/** What the audience learns about the present requester. */
+export interface OxyRequesterContext {
+    readonly userId: string;
+    readonly agentId: string;
+    readonly applicationId: string;
+    readonly credentialId: string;
+    readonly jti: string;
+    readonly expiresAt: string;
+}
+export interface OxyRequesterAssertionRequest extends OxyAuthRequest {
+    oxyRequester?: OxyRequesterContext;
+}
+export interface OxyRequesterAssertionAuthOptions {
+    /** This service's audience name, e.g. `alia`. */
+    readonly audience: string;
+    /** Defaults to `https://api.oxy.so`. */
+    readonly issuer?: string;
+    /** Defaults to `/capabilities/.well-known/jwks.json` on the introspector's origin. */
+    readonly jwksUrl?: string;
+    readonly resolvePublicKey?: (keyId: string) => Promise<KeyObject | undefined>;
+    readonly now?: () => Date;
+    /** Observability hook. Receives ids only, never the assertion. */
+    readonly onRejected?: (event: {
+        readonly code: string;
+        readonly status: number;
+        readonly applicationId: string | null;
+    }) => void;
+}
+/**
+ * Accepts an `X-Oxy-Requester-Assertion` presented beside a VERIFIED service
+ * 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
+ * consume an assertion.
+ */
+export declare function createOxyRequesterAssertionAuth(introspector: OxyRequesterAssertionIntrospector, options: OxyRequesterAssertionAuthOptions): RequestHandler;

package/package.json

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

package/src/index.ts

@@ -81,7 +81,7 @@ export type {
     PushTokenPlatform,
     RegisterPushTokenInput,
 } from './mixins/OxyServices.notifications';
-export type { ServiceApp, ServiceActingAsVerification } from './mixins/OxyServices.utility';
+export type { ServiceApp, ServiceActingAsVerification, OxyAuthRefusal } from './mixins/OxyServices.utility';
 export type {
     ContactDiscoveryMatch,
     ContactDiscoveryResponse,
@@ -136,6 +136,8 @@ export type {
     DelegationCatalogBinding,
     DelegationGrantView,
     PutAccountCapabilityPolicyInput,
+    RequesterAssertionGrant,
+    RequesterAssertionIntrospection,
     UpdateDelegationGrantInput,
 } from './mixins/OxyServices.agency';
 

package/src/mixins/OxyServices.agency.ts

@@ -97,6 +97,25 @@ export interface CapabilityExecutionAuthorization {
   updatedAt: string;
 }
 
+/** A present-requester assertion minted for a product backend (ADR 0025). */
+export interface RequesterAssertionGrant {
+  assertion: string;
+  expiresAt: string;
+  requesterAccountId: string;
+  agentId: string;
+}
+
+/** Oxy's live answer to the audience that consumed an assertion (ADR 0025). */
+export interface RequesterAssertionIntrospection {
+  active: boolean;
+  requesterAccountId?: string;
+  agentId?: string;
+  applicationId?: string;
+  credentialId?: string;
+  jti?: string;
+  expiresAt?: string;
+}
+
 function query(path: string, key: string, value: string): string {
   return `${path}?${key}=${encodeURIComponent(value)}`;
 }
@@ -273,5 +292,62 @@ export function OxyServicesAgencyMixin<T extends typeof OxyServicesBase>(Base: T
         throw this.handleError(error);
       }
     }
+
+    /**
+     * Product backend → Oxy: trade the signed-in requester's access token for a
+     * one-use assertion naming `agentId` (ADR 0025). Authenticated with THIS
+     * instance's service credential (`configureServiceAuth`). `subjectToken` is
+     * sent 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: {
+      agentId: string;
+      subjectToken: string;
+    }): Promise<RequesterAssertionGrant> {
+      try {
+        const serviceToken = await (this as unknown as { getServiceToken(): Promise<string> }).getServiceToken();
+        return await this.makeRequest<RequesterAssertionGrant>(
+          'POST',
+          '/internal/native-agents/requester-assertions',
+          { agentId: input.agentId, subjectToken: input.subjectToken },
+          {
+            cache: false,
+            retry: false,
+            timeout: 5000,
+            headers: { Authorization: `Bearer ${serviceToken}` },
+          },
+        );
+      } catch (error) {
+        throw this.handleError(error);
+      }
+    }
+
+    /**
+     * Audience → Oxy: verify, live-revalidate and CONSUME an assertion. A second
+     * call with the same assertion answers `active: false`. Authenticated with
+     * the audience's own service credential.
+     */
+    async introspectRequesterAssertion(input: {
+      assertion: string;
+      presenter: { applicationId: string; credentialId: string };
+    }): Promise<RequesterAssertionIntrospection> {
+      try {
+        const serviceToken = await (this as unknown as { getServiceToken(): Promise<string> }).getServiceToken();
+        return await this.makeRequest<RequesterAssertionIntrospection>(
+          'POST',
+          '/internal/native-agents/requester-assertions/introspect',
+          { assertion: input.assertion, presenter: input.presenter },
+          {
+            cache: false,
+            retry: false,
+            timeout: 5000,
+            headers: { Authorization: `Bearer ${serviceToken}` },
+          },
+        );
+      } catch (error) {
+        throw this.handleError(error);
+      }
+    }
   };
 }