@oxyhq/core 12.10.5 → 12.11.0

package/src/mixins/OxyServices.auth.ts

@@ -58,12 +58,59 @@ export interface PublicKeyCheckResponse {
 // "Sign in with Oxy" — cross-device QR / app-to-app handoff (Workstream C)
 // ===========================================================================
 
+/**
+ * How a "Sign in with Oxy" request finalizes once the approver authorizes it.
+ *
+ * ONE request (`AuthSession`) serves every delivery surface — popup, push, QR,
+ * deep link — so the purpose describes the FINALIZATION, never the transport:
+ *
+ * - `device_sign_in` — the classic device flow. The initiator exchanges its
+ *   secret `sessionToken` for the first access token via `claimSessionByToken`.
+ * - `oauth_authorization` — the request additionally carries an OAuth binding
+ *   ({@link CommonsOAuthContext}), so it finalizes into a single-use
+ *   authorization CODE via {@link OxyServicesAuthMixin.finalizeCommonsOAuth}.
+ *   The caller still performs the PKCE token exchange itself.
+ */
+export type CommonsSignInPurpose = 'device_sign_in' | 'oauth_authorization';
+
+/**
+ * OAuth binding attached to a "Sign in with Oxy" request so a single
+ * `AuthSession` can finalize into a standard OAuth authorization code instead of
+ * a device-flow session.
+ *
+ * Only the minimum request binding is carried here — everything else (the app's
+ * name, icon, registered redirect URIs, trust flags) is owned server-side by the
+ * `Application` the `clientId` resolves to and is never client-supplied.
+ *
+ * The PKCE `codeVerifier` NEVER appears here: only its S256 `codeChallenge`
+ * crosses the wire, exactly as in the redirect flow. The RP-owned OAuth `state`
+ * also stays with the relying party, which validates it locally.
+ */
+export interface CommonsOAuthContext {
+  /** Exact registered redirect URI the authorization code will be returned to. */
+  redirectUri: string;
+  /** PKCE `BASE64URL(SHA-256(codeVerifier))` (RFC 7636 §4.2); the verifier stays client-side. */
+  codeChallenge: string;
+  /** PKCE transformation method. Always `S256` — `plain` is not accepted. */
+  codeChallengeMethod: 'S256';
+  /** Space-delimited OAuth scope string; the server normalizes and validates it. */
+  scope?: string;
+  /**
+   * Optional delegated account the application will act AS (an organization or
+   * project the identity is a member of). The identity approving the request
+   * does not change; the server verifies the identity's permission to act as
+   * this account before finalizing.
+   */
+  subjectAccountId?: string;
+}
+
 /**
  * Handle returned by {@link OxyServicesAuthMixin.startCommonsSignIn} for a
  * relying-party app initiating a "Sign in with Oxy" flow.
  *
  * `sessionToken` is the SECRET, high-entropy device-flow credential — it stays
- * on the initiating client, is exchanged once via `claimSessionByToken`, and is
+ * on the initiating client, is exchanged once via `claimSessionByToken` (device
+ * sign-in) or {@link OxyServicesAuthMixin.finalizeCommonsOAuth} (OAuth), and is
  * NEVER placed in the QR/deep-link. `authorizeCode` is the PUBLIC handle carried
  * in `qrPayload`; the approver (Commons) resolves it via
  * {@link OxyServicesAuthMixin.getCommonsApprovalInfo}.
@@ -81,16 +128,79 @@ export interface CommonsSignInHandle {
   status: string;
 }
 
-/** Poll result for a "Sign in with Oxy" device-flow session (`GET /auth/session/status`). */
+/**
+ * Poll result for a "Sign in with Oxy" device-flow session
+ * (`GET /auth/session/status`).
+ *
+ * The authoritative state machine stays small — `pending → authorized →
+ * consumed`, plus `cancelled` / `expired` — and lives in `status`. Delivery
+ * PROGRESS (`pushSentAt`, `openedAt`) is carried as timestamps beside it, never
+ * as competing statuses, so a progress signal can never be mistaken for an
+ * authorization.
+ */
 export interface CommonsSignInStatus {
   /** True once an approver has authorized the session. */
   authorized: boolean;
-  /** The authorized session id (present once `authorized`). */
+  /** The authorized session id (present once `authorized` for device sign-in). */
   sessionId?: string;
   /** The approving identity's public key (present once `authorized`). */
   publicKey?: string;
   /** Lifecycle status (`'pending'` | `'authorized'` | `'cancelled'` | `'expired'`). */
   status?: string;
+  /**
+   * How this request finalizes. Unrecognized/missing values degrade to
+   * `device_sign_in` so an older API never misroutes an OAuth finalize.
+   */
+  purpose?: CommonsSignInPurpose;
+  /**
+   * ISO-8601 timestamp of when the request was pushed to a known Commons
+   * installation, or `null` when no push has been sent (including on a server
+   * that predates delivery progress). Progress only — it never implies the push
+   * was received, opened, or approved.
+   */
+  pushSentAt: string | null;
+  /**
+   * ISO-8601 timestamp of when the approval route was opened in Commons, or
+   * `null` when it has not been opened. Reported by the approver via
+   * {@link OxyServicesAuthMixin.markCommonsApprovalOpened}; it is an
+   * un-authenticated progress hint used only to advance the waiting UI, and is
+   * NEVER evidence that the request was approved.
+   */
+  openedAt: string | null;
+}
+
+/**
+ * Outcome of asking Oxy to deliver a pending sign-in request to the identity's
+ * known Commons installations (`POST /auth/session/deliver/:authorizeCode`).
+ *
+ * `targets: 0` is a NORMAL outcome, not a failure: it simply means no capable
+ * Commons installation is registered, so push is not a usable route and the
+ * caller shows the QR instead. Feed `targets` into `selectCommonsDelivery`
+ * (`utils/commonsDelivery`) rather than branching on it ad hoc.
+ */
+export interface CommonsDeliveryResult {
+  /** Whether the server dispatched the request to at least one installation. */
+  delivered: boolean;
+  /** How many eligible Commons installations it was dispatched to (`0` is normal). */
+  targets: number;
+}
+
+/**
+ * The account an application will act AS once the request is approved, when the
+ * request delegates to an organization/project rather than the approver's own
+ * personal account. Resolved and sanitized server-side from the request's
+ * `subjectAccountId`, so it is safe to display in the approval UI.
+ *
+ * The identity approving stays the identity: Commons renders this as a distinct
+ * "will act as" line, never as a change of who is signing.
+ */
+export interface CommonsApprovalSubjectAccount {
+  /** The delegated account's id. */
+  id: string;
+  /** The delegated account's handle. */
+  username: string;
+  /** Optional human-readable name; absent when the account has no real name. */
+  displayName?: string;
 }
 
 /**
@@ -113,6 +223,32 @@ export interface CommonsApprovalInfo {
    * "not verified") by {@link OxyServicesAuthMixin.getCommonsApprovalInfo}.
    */
   originVerified: boolean;
+  /**
+   * COARSE, display-only label of the client that STARTED the request
+   * (`"Chrome on Windows"`), resolved server-side from the requesting browser —
+   * NEVER from the QR payload. Render it verbatim as a secondary line under the
+   * origin; it is the whole descriptor the platform has (no raw User-Agent, no
+   * IP, no location is ever collected for it).
+   *
+   * `null` whenever the server has no browser context to describe: native
+   * requesters, unidentifiable User-Agents, and any API that predates the field.
+   * Omit the line entirely in that case — never substitute a guess.
+   */
+  requesterLabel: string | null;
+  /**
+   * How this request finalizes. Always present — an unrecognized or missing
+   * server value degrades to `'device_sign_in'`, the behaviour every server has
+   * always had, so an older API never makes the approver believe it is granting
+   * an OAuth authorization.
+   */
+  purpose: CommonsSignInPurpose;
+  /**
+   * The delegated account the application will act as, or `null` when the
+   * request is for the approver's own account. Always present — a missing or
+   * malformed server value degrades to `null` (fail-safe to "no delegation"),
+   * so a partial payload can never imply a broader grant than was requested.
+   */
+  subjectAccount: CommonsApprovalSubjectAccount | null;
   /** Server-authoritative expiry (epoch ms or ISO-8601 string from the API). */
   expiresAt: number | string;
   /** Session lifecycle status. */
@@ -121,24 +257,114 @@ export interface CommonsApprovalInfo {
 
 /**
  * @internal Raw server response of `GET /auth/session/approve-info/:code`.
- * `originVerified` is typed loosely here because older servers may omit it (or
- * send a non-boolean); the SDK coerces it to a strict `boolean` when mapping
- * into {@link CommonsApprovalInfo}.
+ * `originVerified`, `purpose` and `subjectAccount` are typed loosely here
+ * because older servers may omit them (or send an unexpected shape); the SDK
+ * narrows each one fail-safe when mapping into {@link CommonsApprovalInfo}.
  */
 interface CommonsApprovalInfoResponse {
   application: PublicApplication | null;
   scopes: string[];
   boundOrigin?: string;
   originVerified?: unknown;
+  requesterLabel?: unknown;
+  purpose?: unknown;
+  subjectAccount?: unknown;
   expiresAt: number | string;
   status: string;
 }
 
+/**
+ * @internal Narrow an untrusted `requesterLabel` from the approve-info response.
+ *
+ * Returns the trimmed label only when the server sent a real, non-empty string;
+ * everything else — absent (an API that predates the field), `null` (a native
+ * requester the server could not describe), or a non-string — degrades to
+ * `null`, so the approval UI drops the line instead of rendering a blank or a
+ * coerced value under the app it is about to authorize.
+ */
+function parseCommonsRequesterLabel(value: unknown): string | null {
+  if (typeof value !== 'string') {
+    return null;
+  }
+  const label = value.trim();
+  return label.length > 0 ? label : null;
+}
+
+/**
+ * @internal Narrow an untrusted `subjectAccount` from the approve-info response.
+ *
+ * Returns `null` unless the value is an object carrying a non-empty string `id`
+ * AND `username` — the two fields the approval UI needs to name the delegated
+ * account. A half-populated object is rejected whole rather than rendered with
+ * blanks, and `displayName` is only carried through when it is a string.
+ */
+function parseCommonsSubjectAccount(value: unknown): CommonsApprovalSubjectAccount | null {
+  if (value === null || typeof value !== 'object') {
+    return null;
+  }
+  const raw = value as Record<string, unknown>;
+  const { id, username, displayName } = raw;
+  if (typeof id !== 'string' || !id || typeof username !== 'string' || !username) {
+    return null;
+  }
+  return {
+    id,
+    username,
+    ...(typeof displayName === 'string' ? { displayName } : {}),
+  };
+}
+
+/**
+ * @internal Narrow an untrusted delivery-progress timestamp from the status
+ * response.
+ *
+ * Returns the ISO-8601 string unchanged when it is a real, parseable instant,
+ * and `null` for everything else — absent (an older API that has no delivery
+ * progress at all), empty, non-string, or unparseable. Progress is advisory, so
+ * degrading to "no progress yet" is always safe; surfacing a garbage timestamp
+ * to the waiting UI is not.
+ */
+function parseCommonsProgressTimestamp(value: unknown): string | null {
+  if (typeof value !== 'string' || !value) {
+    return null;
+  }
+  return Number.isFinite(Date.parse(value)) ? value : null;
+}
+
 /** Result of approving / denying a "Sign in with Oxy" request. */
 export interface CommonsSignInActionResult {
   success: boolean;
 }
 
+/**
+ * Why the approver denied a "Sign in with Oxy" request. A CLOSED set — the deny
+ * endpoint is unauthenticated, so it accepts no free-form text:
+ *
+ *  - `'declined'` the approver rejected a request they recognised ("Not now").
+ *  - `'not_me'`   the approver did not start the request ("This wasn't me").
+ *                 The only value that records the denial as suspicious rather
+ *                 than an ordinary cancel, so a UI may only offer it where the
+ *                 user genuinely said so.
+ */
+export type CommonsDenyReason = 'declined' | 'not_me';
+
+/**
+ * Result of finalizing an approved, OAuth-bound "Sign in with Oxy" request.
+ *
+ * This is an authorization CODE, not a session: the caller still performs the
+ * standard PKCE token exchange (`exchangeOAuthCode`) with the `codeVerifier` it
+ * has held all along. No access token, refresh token, or device secret is ever
+ * produced by finalization.
+ */
+export interface CommonsOAuthFinalizeResult {
+  /** Single-use OAuth authorization code. */
+  code: string;
+  /** The exact registered redirect URI the request was bound to. */
+  redirectUri: string;
+  /** Lifetime of the authorization code, in seconds. */
+  expiresIn: number;
+}
+
 /** @internal Response shape of the extended `POST /auth/session/create`. */
 interface CommonsSessionCreateResponse {
   authorizeCode: string;
@@ -721,11 +947,16 @@ export function OxyServicesAuthMixin<T extends typeof OxyServicesBase>(Base: T)
     //   A. Same-device shared-keychain SSO (`signInWithSharedIdentity`): a
     //      sibling native app silently mints its own session from the shared
     //      identity key. No user interaction.
-    //   B. QR / app-to-app handoff: a relying party (`startCommonsSignIn` +
-    //      `pollCommonsSignIn` + the existing `claimSessionByToken`) and the
-    //      approver / Commons (`getCommonsApprovalInfo` + `approveCommonsSignIn`
-    //      / `denyCommonsSignIn`). The approver signs with its PRIMARY local
-    //      key; the RP never sees the private key.
+    //   B. QR / app-to-app / popup / push handoff: a relying party
+    //      (`startCommonsSignIn` + `pollCommonsSignIn`, finalized with either
+    //      `claimSessionByToken` or `finalizeCommonsOAuth`) and the approver /
+    //      Commons (`getCommonsApprovalInfo` + `approveCommonsSignIn` /
+    //      `denyCommonsSignIn`). The approver signs with its PRIMARY local key;
+    //      the RP never sees the private key.
+    //
+    //      ONE request serves every delivery surface. The delivery surface is
+    //      not part of the model: only the request's purpose is, and it is fixed
+    //      at creation by whether an OAuth binding was attached.
     // =======================================================================
 
     /**
@@ -793,14 +1024,28 @@ export function OxyServicesAuthMixin<T extends typeof OxyServicesBase>(Base: T)
      * returns the server-issued public `authorizeCode` + ready-to-render
      * `qrPayload`. Render the QR (web) / open the deep-link (same-device); the
      * approver resolves the code and authorizes. Then poll with
-     * {@link pollCommonsSignIn} and, on `authorized`, exchange the
-     * `sessionToken` via the existing `claimSessionByToken`.
+     * {@link pollCommonsSignIn} and finalize.
+     *
+     * ONE request serves every delivery surface, and how it finalizes is decided
+     * here by whether an OAuth binding is attached:
+     *   - no `oauth` (the default): a `device_sign_in` request — on `authorized`,
+     *     exchange the `sessionToken` via the existing `claimSessionByToken`.
+     *   - with `oauth`: an `oauth_authorization` request — on `authorized`, call
+     *     {@link finalizeCommonsOAuth} with the same `sessionToken` to mint the
+     *     single-use authorization code, then exchange it with PKCE.
      *
      * @param params.clientId - The RP's registered OAuth client id
      *   (ApplicationCredential publicKey); required so the server can resolve the
      *   requesting application's identity.
+     * @param params.oauth - Optional OAuth binding ({@link CommonsOAuthContext}).
+     *   Carries only the redirect URI, the PKCE S256 challenge, the requested
+     *   scope, and an optional delegated `subjectAccountId` — never the PKCE
+     *   verifier, the OAuth `state`, or any token.
      */
-    async startCommonsSignIn(params: { clientId: string }): Promise<CommonsSignInHandle> {
+    async startCommonsSignIn(params: {
+      clientId: string;
+      oauth?: CommonsOAuthContext;
+    }): Promise<CommonsSignInHandle> {
       try {
         // High-entropy opaque secret token (256-bit hex). Generated client-side
         // and held only here; the server stores it but never returns it in the
@@ -811,7 +1056,15 @@ export function OxyServicesAuthMixin<T extends typeof OxyServicesBase>(Base: T)
         const res = await this.makeRequest<CommonsSessionCreateResponse>(
           'POST',
           '/auth/session/create',
-          { sessionToken, expiresAt, clientId: params.clientId },
+          {
+            sessionToken,
+            expiresAt,
+            clientId: params.clientId,
+            // Omitted entirely when absent so the device-sign-in body stays
+            // exactly what it has always been (the server reads presence, not a
+            // null, to decide the request's purpose).
+            ...(params.oauth ? { oauth: params.oauth } : {}),
+          },
           // Public/pre-session (no bearer): skip the preflight so a stale
           // near-expiry token cannot re-enter refreshAccessToken while the
           // refresh handler is already in flight (self-await hang).
@@ -834,14 +1087,20 @@ export function OxyServicesAuthMixin<T extends typeof OxyServicesBase>(Base: T)
      * MECHANISM B (relying party) — poll a device-flow session for approval.
      *
      * Backstop for the auth socket. On `authorized` (with a `sessionId`), the
-     * caller exchanges the secret `sessionToken` via the existing
-     * `claimSessionByToken` to mint the first access token.
+     * caller finalizes: `claimSessionByToken` for a `device_sign_in` request,
+     * {@link finalizeCommonsOAuth} for an `oauth_authorization` one.
+     *
+     * Every field is narrowed fail-safe. `authorized` counts only as a literal
+     * `true`, the identifiers only as non-empty strings, and the delivery
+     * progress timestamps degrade to `null` when absent or unparseable — so a
+     * partial or older-API payload can advance the waiting UI at most, never
+     * make it believe a request was approved.
      *
      * @param sessionToken - The secret token from {@link startCommonsSignIn}.
      */
     async pollCommonsSignIn(sessionToken: string): Promise<CommonsSignInStatus> {
       try {
-        return await this.makeRequest<CommonsSignInStatus>(
+        const res = await this.makeRequest<unknown>(
           'GET',
           `/auth/session/status/${encodeURIComponent(sessionToken)}`,
           undefined,
@@ -850,6 +1109,167 @@ export function OxyServicesAuthMixin<T extends typeof OxyServicesBase>(Base: T)
           // refreshAccessToken and await the very promise it runs inside.
           { cache: false, retry: false, skipAuth: true }
         );
+
+        if (res === null || typeof res !== 'object') {
+          throw new Error('auth/session/status returned an unexpected response shape');
+        }
+        const { authorized, sessionId, publicKey, status, purpose, pushSentAt, openedAt } =
+          res as Record<string, unknown>;
+
+        return {
+          authorized: authorized === true,
+          ...(typeof sessionId === 'string' && sessionId ? { sessionId } : {}),
+          ...(typeof publicKey === 'string' && publicKey ? { publicKey } : {}),
+          ...(typeof status === 'string' && status ? { status } : {}),
+          purpose: purpose === 'oauth_authorization' ? 'oauth_authorization' : 'device_sign_in',
+          pushSentAt: parseCommonsProgressTimestamp(pushSentAt),
+          openedAt: parseCommonsProgressTimestamp(openedAt),
+        };
+      } catch (error) {
+        throw this.handleError(error);
+      }
+    }
+
+    /**
+     * MECHANISM B (relying party) — ask Oxy to DELIVER a pending sign-in request
+     * to the identity's known Commons installations.
+     *
+     * This is the automatic half of "one intention, one primary action": rather
+     * than offering the user a menu of transports, the caller asks for delivery
+     * and lets the answer pick the route. Pass the returned `targets` to
+     * `selectCommonsDelivery` (`utils/commonsDelivery`) — `targets: 0` means no
+     * capable Commons installation is registered, which is a NORMAL outcome that
+     * resolves to the QR route, not an error to surface.
+     *
+     * **Requires a bearer.** Delivery is only allowed when Oxy already knows the
+     * intended identity from a trusted authenticated context — a request that
+     * merely carries a username or email typed into an unauthenticated browser
+     * must never be able to ring somebody's phone.
+     *
+     * The push it sends carries only `{ type, approvalUrl }` where the URL holds
+     * the public `authorizeCode` — no display data, no secrets. Commons resolves
+     * everything it shows from `getCommonsApprovalInfo`.
+     *
+     * @param authorizeCode - The public code from {@link startCommonsSignIn}.
+     */
+    async deliverCommonsSignIn(authorizeCode: string): Promise<CommonsDeliveryResult> {
+      try {
+        const res = await this.makeRequest<unknown>(
+          'POST',
+          `/auth/session/deliver/${encodeURIComponent(authorizeCode)}`,
+          undefined,
+          // Bearer REQUIRED (unlike its public siblings): the identity to
+          // deliver to comes from the authenticated caller, never the code.
+          { cache: false },
+        );
+
+        if (res === null || typeof res !== 'object') {
+          throw new Error('auth/session/deliver returned an unexpected response shape');
+        }
+        const { delivered, targets } = res as Record<string, unknown>;
+        // Both fields drive the route choice, so a partial payload is rejected
+        // outright rather than defaulted into a route the server never chose.
+        if (
+          typeof delivered !== 'boolean' ||
+          typeof targets !== 'number' ||
+          !Number.isInteger(targets) ||
+          targets < 0
+        ) {
+          throw new Error('auth/session/deliver returned an incomplete delivery result');
+        }
+
+        return { delivered, targets };
+      } catch (error) {
+        throw this.handleError(error);
+      }
+    }
+
+    /**
+     * MECHANISM B (approver / Commons) — report that the approval route was
+     * OPENED, so the waiting relying party can show "Opened in Commons".
+     *
+     * Progress only. It is idempotent, applies to a `pending` request alone, and
+     * records a timestamp (`openedAt`) — it never approves, authorizes, or
+     * advances the authorization state machine. Public, like the other approver
+     * handles: the approver has only the public `authorizeCode` at this point
+     * and has not yet signed anything.
+     *
+     * Best-effort by nature — a failure here costs the user only a progress
+     * line, so callers are free to ignore a rejection and continue to the
+     * approval screen.
+     *
+     * @param authorizeCode - The public code scanned from the QR / deep-link / push.
+     */
+    async markCommonsApprovalOpened(authorizeCode: string): Promise<void> {
+      try {
+        await this.makeRequest<unknown>(
+          'POST',
+          `/auth/session/opened/${encodeURIComponent(authorizeCode)}`,
+          undefined,
+          // Public (no bearer) — skip the preflight, exactly like approve-info.
+          { cache: false, skipAuth: true },
+        );
+      } catch (error) {
+        throw this.handleError(error);
+      }
+    }
+
+    /**
+     * MECHANISM B (relying party) — finalize an APPROVED, OAuth-bound request
+     * into a single-use OAuth authorization code.
+     *
+     * The OAuth counterpart of `claimSessionByToken`: same secret credential,
+     * same single-use semantics, different output. Call it once the request the
+     * RP started with an `oauth` binding reports `authorized`; the server
+     * atomically mints exactly ONE `AuthCode` bound to the redirect URI, PKCE
+     * challenge, scopes, approving identity, and any delegated subject account
+     * the request was created with. A second call cannot mint another code.
+     *
+     * The result is an authorization CODE, never a token — the caller completes
+     * the flow with the ordinary PKCE exchange (`exchangeOAuthCode`) using the
+     * `codeVerifier` it never sent anywhere. Nothing here is exposed to the
+     * popup: the code travels back through the registered callback, and the
+     * main window owns the verifier.
+     *
+     * Like `claimSessionByToken`, this needs no Authorization header — the
+     * high-entropy SECRET `sessionToken` IS the credential. Never pass the
+     * public `authorizeCode` here; it is the approver's handle, not the
+     * initiator's. Every server-side failure (wrong/expired/already-finalized
+     * request, non-OAuth purpose, missing permission for the delegated account)
+     * surfaces as one generic error, so nothing about the request's state can be
+     * probed from outside.
+     *
+     * @param sessionToken - The secret token from {@link startCommonsSignIn}.
+     */
+    async finalizeCommonsOAuth(sessionToken: string): Promise<CommonsOAuthFinalizeResult> {
+      try {
+        const res = await this.makeRequest<unknown>(
+          'POST',
+          `/auth/session/finalize/${encodeURIComponent(sessionToken)}`,
+          undefined,
+          // Body-authenticated by the path's secret token (no bearer) — skip the
+          // preflight, exactly like the device-flow claim.
+          { cache: false, skipAuth: true },
+        );
+
+        if (res === null || typeof res !== 'object') {
+          throw new Error('auth/session/finalize returned an unexpected response shape');
+        }
+        const { code, redirectUri, expiresIn } = res as Record<string, unknown>;
+        // All three fields are load-bearing for the exchange that follows, so a
+        // partial payload is rejected outright rather than returned half-parsed.
+        if (
+          typeof code !== 'string' ||
+          !code ||
+          typeof redirectUri !== 'string' ||
+          !redirectUri ||
+          typeof expiresIn !== 'number' ||
+          !Number.isFinite(expiresIn)
+        ) {
+          throw new Error('auth/session/finalize returned an incomplete authorization code');
+        }
+
+        return { code, redirectUri, expiresIn };
       } catch (error) {
         throw this.handleError(error);
       }
@@ -859,9 +1279,10 @@ export function OxyServicesAuthMixin<T extends typeof OxyServicesBase>(Base: T)
      * MECHANISM B (approver / Commons) — resolve the TRUSTED identity of a
      * sign-in request from its public `authorizeCode`.
      *
-     * The returned `application` is resolved server-side and is the only safe
-     * thing to display in the approval UI — NEVER trust the app/name/origin
-     * strings carried in the QR payload. Public (no auth required).
+     * The returned `application` and `subjectAccount` are resolved server-side
+     * and are the only safe things to display in the approval UI — NEVER trust
+     * the app/name/origin strings carried in the QR payload. Public (no auth
+     * required).
      *
      * @param authorizeCode - The public code scanned from the QR / deep-link.
      */
@@ -883,6 +1304,17 @@ export function OxyServicesAuthMixin<T extends typeof OxyServicesBase>(Base: T)
           // missing or non-boolean value (older server, malformed response)
           // coerces to `false` so a stale server can never imply trust.
           originVerified: raw.originVerified === true,
+          // Same discipline: a missing/blank/non-string label degrades to null
+          // (an older API, or a native requester with no browser to describe),
+          // and the approver simply omits the "where from" line.
+          requesterLabel: parseCommonsRequesterLabel(raw.requesterLabel),
+          // Same discipline: only the literal OAuth purpose opts into OAuth
+          // finalization. Anything else — including a server that predates this
+          // field — is the plain device sign-in it has always been.
+          purpose: raw.purpose === 'oauth_authorization' ? 'oauth_authorization' : 'device_sign_in',
+          // A missing/partial delegated account degrades to "no delegation"
+          // rather than a half-rendered "will act as" line.
+          subjectAccount: parseCommonsSubjectAccount(raw.subjectAccount),
           expiresAt: raw.expiresAt,
           status: raw.status,
         };
@@ -944,13 +1376,21 @@ export function OxyServicesAuthMixin<T extends typeof OxyServicesBase>(Base: T)
      * device-flow session so the RP stops waiting.
      *
      * @param authorizeCode - The public code being denied.
+     * @param reason - Optional closed-set reason ({@link CommonsDenyReason}).
+     *   Pass `'not_me'` ONLY when the user actually reported the request as one
+     *   they did not start — the server records it as a suspicious denial rather
+     *   than an ordinary cancel. Omitting it sends the exact body this endpoint
+     *   has always received.
      */
-    async denyCommonsSignIn(authorizeCode: string): Promise<CommonsSignInActionResult> {
+    async denyCommonsSignIn(
+      authorizeCode: string,
+      reason?: CommonsDenyReason,
+    ): Promise<CommonsSignInActionResult> {
       try {
         return await this.makeRequest<CommonsSignInActionResult>(
           'POST',
           `/auth/session/deny/${encodeURIComponent(authorizeCode)}`,
-          undefined,
+          reason ? { reason } : undefined,
           // Public (no auth required) — skip the bearer preflight.
           { cache: false, skipAuth: true }
         );
@@ -1270,7 +1710,7 @@ export function OxyServicesAuthMixin<T extends typeof OxyServicesBase>(Base: T)
         const deviceId = (record.deviceId ?? record.device_id) as string | undefined;
         const deviceSecret = (record.deviceSecret ?? record.device_secret) as string | undefined;
         const userRaw = record.user;
-        if (!sessionId || !deviceId || !userRaw || typeof userRaw !== 'object') {
+        if (!sessionId || !deviceId || !deviceSecret || !userRaw || typeof userRaw !== 'object') {
           throw new Error('auth/oauth/token returned an incomplete session payload');
         }
         const userObj = userRaw as Record<string, unknown>;