@oxyhq/core 3.10.1 → 3.12.0

package/dist/esm/mixins/OxyServices.auth.js

@@ -1,7 +1,15 @@
 import { OxyAuthenticationError } from '../OxyServices.errors.js';
+import { KeyManager } from '../crypto/keyManager.js';
+import { SignatureService } from '../crypto/signatureService.js';
 import { loadNodeCrypto } from '../utils/platformCrypto.js';
 import { logger } from '../utils/loggerUtils.js';
 import { normalizeUserIdentity, normalizeUserIdentityOrNull } from '../utils/userIdentity.js';
+/**
+ * Default lifetime of a "Sign in with Oxy" device-flow session / authorize code.
+ * Matches the authorize-code TTL the server enforces (5 minutes). The server's
+ * returned `expiresAt` is authoritative; this is only the client-proposed value.
+ */
+const COMMONS_SIGN_IN_EXPIRY_MS = 5 * 60 * 1000;
 /**
  * Sentinel error raised when getServiceToken() is called with a known apiKey
  * but a non-matching secret. Indicates either credential drift in the caller
@@ -143,11 +151,25 @@ export function OxyServicesAuthMixin(Base) {
             try {
                 return await pending;
             }
+            catch (error) {
+                // Do not retain unauthenticated cache entries. If the initial
+                // /auth/service-token request fails (for example, wrong apiSecret),
+                // leaving the pre-seeded empty entry would cause later calls with the
+                // real secret for the same apiKey to fail locally as a credential
+                // mismatch without ever contacting the server. Keep previously-issued
+                // stale tokens on refresh failures, but remove never-authenticated
+                // entries.
+                const failed = this._serviceTokenCache.get(cacheKey);
+                if (failed?.pending === pending && !failed.token) {
+                    this._serviceTokenCache.delete(cacheKey);
+                }
+                throw error;
+            }
             finally {
                 // Clear the in-flight slot; the entry itself (with fresh token / expiry)
                 // is updated inside _doFetchServiceToken before we land here.
                 const settled = this._serviceTokenCache.get(cacheKey);
-                if (settled) {
+                if (settled?.pending === pending) {
                     settled.pending = null;
                 }
             }
@@ -413,6 +435,173 @@ export function OxyServicesAuthMixin(Base) {
                 throw this.handleError(error);
             }
         }
+        // =======================================================================
+        // "Sign in with Oxy" — handoff (Workstream C)
+        //
+        // Two mechanisms share the same challenge/verify + device-flow primitives:
+        //   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.
+        // =======================================================================
+        /**
+         * MECHANISM A — same-device shared-keychain SSO.
+         *
+         * Native-only. If this device holds a shared identity (the cross-app
+         * `group.so.oxy.shared` keychain key), prove control of it and mint a
+         * session: `requestChallenge(sharedPublicKey)` → `signChallengeWithSharedKey`
+         * → `verifyChallenge` (which plants the tokens). Returns `null` on web or
+         * when no shared identity is present — never throws for the absent-identity
+         * case, so a cold-boot caller can fall through to the next step.
+         *
+         * The cold-boot wiring that CALLS this lives in `OxyContext`
+         * (`@oxyhq/services`); this method just performs the exchange.
+         */
+        async signInWithSharedIdentity(opts = {}) {
+            try {
+                // `hasSharedIdentity()` already returns false on web (the shared
+                // keychain is native-only), so this short-circuits the web case without
+                // a wasted challenge round-trip.
+                if (!(await KeyManager.hasSharedIdentity())) {
+                    return null;
+                }
+                const sharedPublicKey = await KeyManager.getSharedPublicKey();
+                if (!sharedPublicKey) {
+                    return null;
+                }
+                const { challenge } = await this.requestChallenge(sharedPublicKey);
+                const signed = await SignatureService.signChallengeWithSharedKey(challenge);
+                // `signed.challenge` carries the SIGNATURE (mirrors `signChallenge`).
+                return await this.verifyChallenge(signed.publicKey, challenge, signed.challenge, signed.timestamp, opts.deviceName, opts.deviceFingerprint);
+            }
+            catch (error) {
+                throw this.handleError(error);
+            }
+        }
+        /**
+         * MECHANISM B (relying party) — begin a "Sign in with Oxy" handoff.
+         *
+         * Generates a secret device-flow `sessionToken` client-side (it never
+         * appears in the QR), registers it with `POST /auth/session/create`, and
+         * 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`.
+         *
+         * @param params.clientId - The RP's registered OAuth client id
+         *   (ApplicationCredential publicKey); required so the server can resolve the
+         *   requesting application's identity.
+         */
+        async startCommonsSignIn(params) {
+            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
+                // QR. Reuses the platform-safe random generator.
+                const sessionToken = await SignatureService.generateChallenge();
+                const expiresAt = Date.now() + COMMONS_SIGN_IN_EXPIRY_MS;
+                const res = await this.makeRequest('POST', '/auth/session/create', { sessionToken, expiresAt, clientId: params.clientId }, { cache: false });
+                return {
+                    sessionToken,
+                    authorizeCode: res.authorizeCode,
+                    qrPayload: res.qrPayload,
+                    expiresAt: res.expiresAt ?? expiresAt,
+                    status: res.status,
+                };
+            }
+            catch (error) {
+                throw this.handleError(error);
+            }
+        }
+        /**
+         * 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.
+         *
+         * @param sessionToken - The secret token from {@link startCommonsSignIn}.
+         */
+        async pollCommonsSignIn(sessionToken) {
+            try {
+                return await this.makeRequest('GET', `/auth/session/status/${encodeURIComponent(sessionToken)}`, undefined, { cache: false, retry: false });
+            }
+            catch (error) {
+                throw this.handleError(error);
+            }
+        }
+        /**
+         * 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).
+         *
+         * @param authorizeCode - The public code scanned from the QR / deep-link.
+         */
+        async getCommonsApprovalInfo(authorizeCode) {
+            try {
+                return await this.makeRequest('GET', `/auth/session/approve-info/${encodeURIComponent(authorizeCode)}`, undefined, { cache: false });
+            }
+            catch (error) {
+                throw this.handleError(error);
+            }
+        }
+        /**
+         * MECHANISM B (approver / Commons) — approve a sign-in request by signing a
+         * fresh challenge with the PRIMARY local identity key.
+         *
+         * Commons holds the user's identity as its primary key (not the shared
+         * key), so this uses `signChallenge`. The signed-but-cookieless authorize
+         * endpoint resolves the user from the verified signer — the RP that started
+         * the flow then claims its session. Native-only (requires a local identity).
+         *
+         * @param params.authorizeCode - The public code being approved.
+         * @param params.deviceName - Optional human-readable device label.
+         * @param params.deviceFingerprint - Optional device fingerprint.
+         */
+        async approveCommonsSignIn(params) {
+            try {
+                const publicKey = await KeyManager.getPublicKey();
+                if (!publicKey) {
+                    throw new Error('No identity found on this device. Create or import an identity first.');
+                }
+                const { challenge } = await this.requestChallenge(publicKey);
+                const signed = await SignatureService.signChallenge(challenge);
+                return await this.makeRequest('POST', `/auth/session/authorize-signed/${encodeURIComponent(params.authorizeCode)}`, {
+                    // `signed.challenge` carries the SIGNATURE; `challenge` is the
+                    // original server-issued challenge string.
+                    publicKey: signed.publicKey,
+                    challenge,
+                    signature: signed.challenge,
+                    timestamp: signed.timestamp,
+                    ...(params.deviceName ? { deviceName: params.deviceName } : {}),
+                    ...(params.deviceFingerprint ? { deviceFingerprint: params.deviceFingerprint } : {}),
+                }, { cache: false });
+            }
+            catch (error) {
+                throw this.handleError(error);
+            }
+        }
+        /**
+         * MECHANISM B (approver / Commons) — deny a sign-in request, cancelling the
+         * device-flow session so the RP stops waiting.
+         *
+         * @param authorizeCode - The public code being denied.
+         */
+        async denyCommonsSignIn(authorizeCode) {
+            try {
+                return await this.makeRequest('POST', `/auth/session/deny/${encodeURIComponent(authorizeCode)}`, undefined, { cache: false });
+            }
+            catch (error) {
+                throw this.handleError(error);
+            }
+        }
         /**
          * Refresh every device-local refresh-cookie slot in a single round trip
          * (Google-style multi-account rebuild).