@oxy.so/core 1.4.0 → 1.5.1

package/dist/types/OxyServices.d.ts

@@ -59,6 +59,7 @@
 import { type LinkedHttpClient, type OxyConfig } from './OxyServices.base';
 import { AssetUrlResolutionError, OxyAuthenticationError, OxyAuthenticationTimeoutError, ServiceAssetMetadataError } from './OxyServices.errors';
 import { composeOxyServices } from './mixins';
+import type { OxyAuthRefusal } from './mixins/OxyServices.utility';
 /**
  * OxyServices - Unified client library for interacting with the Oxy API
  *
@@ -105,6 +106,7 @@ export interface OxyServices extends InstanceType<ReturnType<typeof composeOxySe
         onError?: (error: unknown) => unknown;
         loadUser?: boolean;
         optional?: boolean;
+        onRefusal?: (refusal: OxyAuthRefusal) => void;
         serviceTokenJwksUrl?: string;
         jwtSecret?: string;
         expectedIssuer?: string;
@@ -115,6 +117,7 @@ export interface OxyServices extends InstanceType<ReturnType<typeof composeOxySe
     }): (socket: unknown, next: (err?: Error) => void) => Promise<void>;
     serviceAuth(options?: {
         debug?: boolean;
+        onRefusal?: (refusal: OxyAuthRefusal) => void;
         serviceTokenJwksUrl?: string;
         jwtSecret?: string;
         expectedIssuer?: string;

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';

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.
@@ -242,6 +290,8 @@ export declare function OxyServicesUtilityMixin<T extends typeof OxyServicesBase
          */
         serviceAuth(options?: {
             debug?: boolean;
+            /** Observe refusals on the service lane; forwarded straight to `auth()`. */
+            onRefusal?: (refusal: OxyAuthRefusal) => void;
             /** @deprecated Oxy-API-only HS256 transition; external verifiers use JWKS. */
             jwtSecret?: string;
             serviceTokenJwksUrl?: string;
@@ -362,6 +412,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';

package/package.json

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

package/src/OxyServices.ts

@@ -61,6 +61,7 @@ import { AssetUrlResolutionError, OxyAuthenticationError, OxyAuthenticationTimeo
 
 // Import mixin composition helper
 import { composeOxyServices } from './mixins';
+import type { OxyAuthRefusal } from './mixins/OxyServices.utility';
 
 /**
  * OxyServices - Unified client library for interacting with the Oxy API
@@ -120,11 +121,18 @@ export interface OxyServices extends InstanceType<ReturnType<typeof composeOxySe
   createLinkedClient(config: OxyConfig): LinkedHttpClient;
 
   // Express.js middleware
+  //
+  // This list is the one CONSUMERS see: `OxyAuthMiddlewareOptions` in
+  // `server/auth.ts` is `Parameters<OxyServices['auth']>[0]`, so an option that
+  // exists on the mixin and not here does not exist for anybody outside this
+  // package. `onRefusal` shipped in 1.5.0 exactly that way — present in the
+  // implementation, invisible to every host that tried to pass it.
   auth(options?: {
     debug?: boolean;
     onError?: (error: unknown) => unknown;
     loadUser?: boolean;
     optional?: boolean;
+    onRefusal?: (refusal: OxyAuthRefusal) => void;
     serviceTokenJwksUrl?: string;
     jwtSecret?: string;
     expectedIssuer?: string;
@@ -139,6 +147,7 @@ export interface OxyServices extends InstanceType<ReturnType<typeof composeOxySe
   // Service-token-only middleware (delegates to auth() internally)
   serviceAuth(options?: {
     debug?: boolean;
+    onRefusal?: (refusal: OxyAuthRefusal) => void;
     serviceTokenJwksUrl?: string;
     jwtSecret?: string;
     expectedIssuer?: string;

package/src/__tests__/publicInterfaceParity.test.ts

@@ -0,0 +1,75 @@
+/**
+ * The middleware options a CONSUMER can pass must be the ones the middleware
+ * actually takes.
+ *
+ * `src/OxyServices.ts` re-declares `auth()` and `serviceAuth()` by hand, with
+ * their option objects written out inline, because declaration emit for the
+ * mixin pipeline does not carry them. That hand-written interface is what
+ * downstream packages see — `OxyAuthMiddlewareOptions` in `server/auth.ts` is
+ * literally `Parameters<OxyServices['auth']>[0]` — so an option that exists on
+ * the mixin and not there exists for this package and for nobody else.
+ *
+ * `onRefusal` shipped in 1.5.0 exactly that way: implemented, tested, exported,
+ * and rejected by the first host that tried to pass it
+ * (`TS2345 … has no properties in common with`). Nothing in this package could
+ * see it, because everything in this package resolves the mixin's own
+ * declaration, where the option is present. Only the published `.d.ts` loses it.
+ *
+ * So the check is on the SOURCE TEXT of the two declarations, which is the
+ * thing that diverges. It is not a type test: a type test here reads the merged
+ * interface and passes either way — measured, by deleting the option and
+ * watching `tsc --noEmit` stay green.
+ */
+
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+const SRC = join(__dirname, '..');
+
+/** Every `name?:` key declared directly inside one brace-balanced block. */
+function optionKeys(source: string, startPattern: RegExp): string[] {
+  const match = startPattern.exec(source);
+  if (!match) throw new Error(`declaration not found: ${String(startPattern)}`);
+  let depth = 0;
+  let index = source.indexOf('{', match.index);
+  const open = index;
+  do {
+    const char = source[index];
+    if (char === '{') depth += 1;
+    else if (char === '}') depth -= 1;
+    index += 1;
+  } while (depth > 0 && index < source.length);
+  const body = source.slice(open + 1, index - 1);
+  // Only keys at THIS level: a nested object literal would otherwise contribute
+  // its own keys. None exist today; the guard keeps that from becoming silent.
+  const withoutNested = body.replace(/\{[^{}]*\}/g, '');
+  return [...withoutNested.matchAll(/^\s*(\w+)\??\s*:/gm)].map((m) => m[1] as string).sort();
+}
+
+describe('the public OxyServices interface declares the options the mixin takes', () => {
+  const mixin = readFileSync(join(SRC, 'mixins/OxyServices.utility.ts'), 'utf8');
+  const publicInterface = readFileSync(join(SRC, 'OxyServices.ts'), 'utf8');
+
+  it('auth() — same option names on both declarations', () => {
+    const declared = optionKeys(mixin, /interface AuthMiddlewareOptions/);
+    const published = optionKeys(publicInterface, /^ {2}auth\(options\?: \{/m);
+
+    expect(declared).toContain('onRefusal');
+    expect(published).toEqual(declared);
+  });
+
+  it('serviceAuth() — same option names on both declarations', () => {
+    const declared = optionKeys(mixin, /^ {4}serviceAuth\(options: \{/m);
+    const published = optionKeys(publicInterface, /^ {2}serviceAuth\(options\?: \{/m);
+
+    expect(declared).toContain('onRefusal');
+    expect(published).toEqual(declared);
+  });
+
+  it('reads real declarations rather than matching nothing', () => {
+    // The floor. A regex that stopped matching would make both cases above
+    // compare two empty lists and pass.
+    expect(optionKeys(mixin, /interface AuthMiddlewareOptions/).length).toBeGreaterThan(5);
+    expect(optionKeys(publicInterface, /^ {2}auth\(options\?: \{/m).length).toBeGreaterThan(5);
+  });
+});

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,