@oxy.so/core 1.3.1 → 1.4.0

package/dist/types/index.d.ts

@@ -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/server/index.d.ts

@@ -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.4.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

@@ -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);
+      }
+    }
   };
 }