@oxyhq/core 21.0.0 → 21.0.1

package/src/server/auth.ts

@@ -19,6 +19,12 @@ export interface OxyServiceAppContext {
   appName: string;
   scopes: string[];
   credentialId: string;
+  /**
+   * The Oxy account that owns `appId` and is financially responsible for it.
+   * Read off the VERIFIED service-token claim set — never a user id, and never
+   * the delegated `X-Oxy-User-Id` (ADR 0007).
+   */
+  ownerAccountId: string;
   environment: OxyServiceEnvironment;
 }
 
@@ -84,6 +90,118 @@ export function isOxyAuthenticated(req: Request): req is OxyAuthenticatedRequest
   return getOxyUserId(req) !== null;
 }
 
+/**
+ * The principal a request is CHARGED to, and the identifiers a receipt needs.
+ *
+ * Every field is read from the verified service-token claim set. It is an
+ * OBJECT, not a string, and that is the point: `getOxyUserId` returns a
+ * `string | null`, so a delegated end-user id cannot be passed anywhere an
+ * `OxyBillingPrincipal` is expected. The confusion ADR 0007 forbids —
+ * attributing spend to the person a service is acting for rather than to the
+ * service's own account — stops being a code-review question and becomes a
+ * compile error.
+ *
+ * `scopes` are the effective scopes minted into the token (credential ∩
+ * application). Nothing re-intersects them here.
+ */
+export interface OxyBillingPrincipal {
+  /** `applications.owner_account_id` — the financially responsible account. */
+  readonly accountId: string;
+  readonly applicationId: string;
+  readonly credentialId: string;
+  readonly environment: OxyServiceEnvironment;
+  readonly scopes: readonly string[];
+}
+
+/**
+ * The full canonical attribution of ADR 0007 for a request: the billing
+ * principal PLUS the optional delegated end user.
+ *
+ * `delegatedUserId` is named for what it is. It answers "on whose behalf" and
+ * is absent for a machine credential acting for itself — its absence is normal,
+ * and nothing may synthesize one. If removing it would change what any account
+ * is charged, the code reading it is wrong.
+ */
+export interface OxyRequestAttribution extends OxyBillingPrincipal {
+  readonly delegatedUserId: string | null;
+}
+
+/**
+ * The billing principal of a request, or `null` when the request carries no
+ * verified service principal (an ordinary user session is not a billable
+ * machine principal — its account is resolved from the account graph, not from
+ * a token claim).
+ *
+ * Reads `req.serviceApp` and NOTHING else: not `req.userId`, not `req.user`,
+ * not `req.serviceActingAs`. That exclusivity is the invariant this function
+ * exists to hold, and `serviceTokenAttribution.test.ts` mutation-tests it.
+ *
+ * **It answers for the SERVICE-TOKEN lane only.** The API's machine-credential
+ * lane (`oxy_sk_*`, issue #972 §2.3) resolves the same five facts into its own
+ * `req.machineCredential`, deliberately never `req.serviceApp` — populating the
+ * latter would hand a self-serve third-party credential the lane that only
+ * platform-trusted applications may enter. So a machine-credential request has
+ * no billing principal HERE and resolves `null`, which fails closed: the caller
+ * must handle it, and `getRequiredOxyBillingPrincipal` throws rather than
+ * charging anyone. One accessor answering for both lanes belongs to the public
+ * inference edge that has to admit both, and it needs the machine principal's
+ * shape to move into this package first.
+ */
+export function getOxyBillingPrincipal(req: Request): OxyBillingPrincipal | null {
+  const serviceApp = (req as OxyAuthRequest).serviceApp;
+  if (!serviceApp) {
+    return null;
+  }
+  const accountId = normalizeId(serviceApp.ownerAccountId);
+  const applicationId = normalizeId(serviceApp.appId);
+  const credentialId = normalizeId(serviceApp.credentialId);
+  if (!accountId || !applicationId || !credentialId) {
+    return null;
+  }
+  return {
+    accountId,
+    applicationId,
+    credentialId,
+    environment: serviceApp.environment,
+    scopes: serviceApp.scopes,
+  };
+}
+
+/**
+ * {@link getOxyBillingPrincipal}, throwing when the request has none. Use on
+ * routes that have already required a service token.
+ */
+export function getRequiredOxyBillingPrincipal(req: Request): OxyBillingPrincipal {
+  const principal = getOxyBillingPrincipal(req);
+  if (!principal) {
+    throw new Error('Request has no verified Oxy service principal');
+  }
+  return principal;
+}
+
+/**
+ * The delegated end user of a service request, or `null`.
+ *
+ * Deliberately reads `req.serviceActingAs` — the grant-verified delegation —
+ * and not `req.userId`, which on a non-service request is the caller's own
+ * session identity and is not a delegation at all.
+ */
+export function getOxyDelegatedUserId(req: Request): string | null {
+  return normalizeId((req as OxyAuthRequest).serviceActingAs?.userId);
+}
+
+/**
+ * The whole attribution tuple for a service request: who pays, which
+ * application and credential, and optionally on whose behalf.
+ */
+export function getOxyRequestAttribution(req: Request): OxyRequestAttribution | null {
+  const principal = getOxyBillingPrincipal(req);
+  if (!principal) {
+    return null;
+  }
+  return { ...principal, delegatedUserId: getOxyDelegatedUserId(req) };
+}
+
 export function getRequiredOxyUserId(req: Request): string {
   const userId = getOxyUserId(req);
   if (!userId) {

package/src/server/index.ts

@@ -18,7 +18,11 @@
 export {
   createOptionalOxyAuth,
   createOxyAuthMiddleware,
+  getOxyBillingPrincipal,
+  getOxyDelegatedUserId,
+  getOxyRequestAttribution,
   getOxyUserId,
+  getRequiredOxyBillingPrincipal,
   getRequiredOxyUserId,
   isOxyAuthenticated,
   requireOxyAuth,
@@ -28,6 +32,8 @@ export type {
   OxyAuthenticatedRequest,
   OxyAuthMiddlewareOptions,
   OxyAuthRequest,
+  OxyBillingPrincipal,
+  OxyRequestAttribution,
   OxyRequestUser,
   OxyServiceActingAsContext,
   OxyServiceAppContext,

package/src/session/__tests__/accountDialogShape.test.ts

@@ -0,0 +1,118 @@
+/**
+ * The two halves of the retired flat account list that a text scan cannot prove
+ * gone.
+ *
+ * `scripts/validate-no-flat-account-list.mjs` bans the identifiers that left the
+ * packages outright — `SwitchableAccount`, `projectSwitchableAccounts`,
+ * `useSwitchableAccounts`, `useAccountStore` and the rest — because each of
+ * those names is unique enough that a match is always a reintroduction. Two
+ * pieces of the same removal are NOT: an `accounts` field on the snapshot and a
+ * `switchTo` method on the controller are ordinary words. `'accounts'` is a live
+ * VIEW name three lines away in the same file, so a scoped grep there would fire
+ * on the thing that is supposed to be there.
+ *
+ * ## Why this is a RUNTIME check and not a type-level one
+ *
+ * A `type Has<S, K> = K extends keyof S ? true : false` assertion reads better
+ * and is checked by nothing here. `packages/core/tsconfig*.json` all carry
+ * `"exclude": ["**\/__tests__"]`, so `tsc` never sees a test file, and
+ * `jest.config.js` sets `diagnostics: false`, so ts-jest transpiles without
+ * typechecking. That version was written first and MUTATION-TESTED: putting
+ * `accounts: string[]` back on the interface and `switchTo()` back on the class
+ * left both assertions green. It is recorded here because the type-level form is
+ * the obvious thing to reach for, and it cannot fail in this package.
+ *
+ * The residual gap of the runtime form is an OPTIONAL field nobody writes —
+ * `accounts?: SwitchableAccount[]` would satisfy `tsc` without appearing on a
+ * snapshot. A REQUIRED one cannot hide: `computeSnapshot()` is strict, so the
+ * field has to be populated, and then it is here. An optional list nothing
+ * writes is not the mechanism coming back.
+ */
+
+import type { DeviceSessionState } from '@oxyhq/contracts';
+import type { OxyServices } from '../../OxyServices';
+import { SessionClient, type SessionClientHost } from '../SessionClient';
+import { createAccountDialogController } from '../accountDialogController';
+
+const host: SessionClientHost = {
+  makeRequest: jest.fn(async () => undefined),
+  getBaseURL: () => 'http://test.invalid',
+  getAccessToken: () => null,
+  getDeviceCredential: () => null,
+  onTokensChanged: () => () => undefined,
+  setTokens: jest.fn(),
+  getCurrentAccountId: () => null,
+};
+
+const oxyServices = {
+  getAccessToken: jest.fn(() => null),
+  getBaseURL: jest.fn(() => 'http://test.invalid'),
+  onTokensChanged: jest.fn(() => () => undefined),
+  getFileDownloadUrl: jest.fn((id: string) => `https://cdn/${id}`),
+} as unknown as OxyServices;
+
+/**
+ * Every key the snapshot carries, and the whole set of them.
+ *
+ * An exact set rather than `not.toContain('accounts')` on purpose: it fails on
+ * ANY new field, not only on one spelled the way the old one was. The snapshot
+ * is a published contract that four surfaces render from, so growing it should
+ * be a deliberate edit here — and a flat list would come back under a new name
+ * (`rows`, `switchable`, `entries`) at least as readily as under the old one,
+ * which a name-specific check would wave through.
+ */
+const SNAPSHOT_KEYS = [
+  'activatingContextId',
+  'activeContext',
+  'commonsAvailability',
+  'directory',
+  'error',
+  'loading',
+  'removingContextId',
+  'removingPrincipalId',
+  'signIn',
+  'view',
+];
+
+describe('the account dialog surface after the flat list was retired', () => {
+  it('carries the server directory, and no flat account list beside it', () => {
+    const controller = createAccountDialogController({
+      oxyServices,
+      sessionClient: new SessionClient(host),
+      clientId: 'oxy_dk_test',
+    });
+
+    const snapshot = controller.getSnapshot();
+
+    // The absence half. `accounts` was the deduped union of the device's
+    // sign-ins and the CALLER's account graph — and a client holds one caller's
+    // graph and cannot enumerate another principal's, so on a device holding two
+    // people it answered with one person's accounts as though they were the
+    // device's.
+    expect(Object.keys(snapshot).sort()).toEqual(SNAPSHOT_KEYS);
+
+    // The positive control, in the same assertion and again here: a snapshot
+    // that stopped being built at all would satisfy "has no `accounts`" too.
+    expect(snapshot).toHaveProperty('directory');
+    expect(snapshot).toHaveProperty('activeContext');
+  });
+
+  it('switches on a context pair, and offers no account-id switch', () => {
+    const controller = createAccountDialogController({
+      oxyServices,
+      sessionClient: new SessionClient(host),
+      clientId: 'oxy_dk_test',
+    });
+
+    // `switchTo(accountId)` could not express WHICH person's route into a shared
+    // organization was being taken, so on a device where two people both reach
+    // one org it chose for the user. `activateContext(contextId)` names the
+    // pair, and `signOutContext` / `signOutPrincipal` are the two removals an
+    // account id likewise cannot name.
+    expect('switchTo' in controller).toBe(false);
+
+    expect(typeof controller.activateContext).toBe('function');
+    expect(typeof controller.signOutContext).toBe('function');
+    expect(typeof controller.signOutPrincipal).toBe('function');
+  });
+});