wip

Author: tsachev

office/.env.example

@@ -33,11 +33,11 @@ IO_BRIDGE_LICENSE_KEY=
 ## Basic Authentication Realm
 IO_BRIDGE_SERVER_AUTH_BASIC_REALM=interop.io
 
-##
+## OAuth2 JWT Issuer URI (used by io.Bridge server for token validation)
 #IO_BRIDGE_SERVER_AUTH_OAUTH2_JWT_ISSUERURI=
 
-##
-IO_BRIDGE_SERVER_AUTH_OAUTH2_JWT_AUDIENCE=
+## OAuth2 JWT Audience (used by io.Bridge server for token validation)
+#IO_BRIDGE_SERVER_AUTH_OAUTH2_JWT_AUDIENCE=
 
 ###############################################################################
 ## Mesh                                                                      ##
@@ -122,5 +122,26 @@ VITE_AUTH0_DOMAIN=
 VITE_AUTH0_CLIENT_ID=
 VITE_AUTH0_AUDIENCE=
 
-##
-#VITE_AUTH0_SCOPES=openid email
+## Auth0 scopes for the browser app (Optional, default is "openid profile email")
+#VITE_AUTH0_SCOPE=openid profile email
+
+###############################################################################
+## Desktop Gateway (Optional — falls back to IO_BRIDGE_* then VITE_*)
+## Use these to configure the gateway independently from the bridge/browser
+###############################################################################
+
+## io.Bridge URL for the gateway mesh connection (falls back to VITE_IO_BRIDGE_URL)
+#IO_GATEWAY_BRIDGE_URL=
+
+## Auth0 Issuer URI for the gateway (falls back to IO_BRIDGE_SERVER_AUTH_OAUTH2_JWT_ISSUERURI, then https://<VITE_AUTH0_DOMAIN>)
+#IO_GATEWAY_AUTH_ISSUERURI=
+
+## Auth0 Client ID for the gateway (falls back to VITE_AUTH0_CLIENT_ID)
+#IO_GATEWAY_AUTH_CLIENT_ID=
+
+## Auth0 Audience for the gateway (falls back to IO_BRIDGE_SERVER_AUTH_OAUTH2_JWT_AUDIENCE, then VITE_AUTH0_AUDIENCE)
+#IO_GATEWAY_AUTH_AUDIENCE=
+
+## Auth0 scopes for the desktop gateway (Optional, default is "openid email offline_access")
+## offline_access is required for automatic token refresh
+#IO_GATEWAY_AUTH0_SCOPE=openid email offline_access

office/auth0/app.ts

@@ -1,6 +1,6 @@
 import type { ServerConfigurer } from "@interopio/gateway-server/web/server";
 import type { Logger } from "@interopio/gateway/logging/api";
-import { randomUUID } from "node:crypto";
+import { createHash, randomBytes, randomUUID } from "node:crypto";
 import { readFileSync } from "node:fs";
 import { resolve } from "node:path";
 
@@ -13,18 +13,29 @@ export type AuthInfo = {
 
 const successPage = readFileSync(resolve(import.meta.dirname, './success.html')).toString();
 
+// PKCE helpers
+function generateCodeVerifier(): string {
+    return randomBytes(32).toString('base64url');
+}
+
+function generateCodeChallenge(verifier: string): string {
+    return createHash('sha256').update(verifier).digest('base64url');
+}
+
 // ---------------------------------------------------------------------------
-// Auth0 integration — Implicit Flow with response_mode=form_post
+// Auth0 integration — Authorization Code Flow with PKCE
 //
 // GET  /login/auth0              → redirects to Auth0 Universal Login
-// POST /login/oauth2/code/auth0  → Auth0 POSTs tokens back here
+// POST /login/oauth2/code/auth0  → Auth0 POSTs authorization code back here;
+//                                  we exchange it for tokens (including a
+//                                  refresh token when offline_access is granted)
 // ---------------------------------------------------------------------------
 export const app = async (
     config: {
         logger: Logger,
         issuerUrl: string,
         clientId: string,
-        scopes?: string,
+        scope?: string,
         audience?: string,
         authInfoResolver: (data: AuthInfo) => void,
     },
@@ -33,16 +44,71 @@ export const app = async (
     }: ServerConfigurer
 ) => {
     const { logger, issuerUrl, clientId } = config;
-    const scopes = config.scopes ?? "openid email";
+    const scopes = config.scope ?? "openid email offline_access";
     const loginCallbackPath = "/login/oauth2/code/auth0";
     const loginUrlPath = "/login/auth0";
 
+    // PKCE state — single-user server, one login at a time
+    let pendingCodeVerifier: string | undefined;
+    let pendingRedirectUri: string | undefined;
+
+    // Mutable reference to the resolved auth info so we can update the token
+    let currentAuthInfo: AuthInfo | undefined;
+
+    // -----------------------------------------------------------------------
+    // Token refresh
+    // -----------------------------------------------------------------------
+    const refreshAccessToken = async (refreshToken: string) => {
+        try {
+            const response = await fetch(`${issuerUrl}/oauth/token`, {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify({
+                    grant_type: 'refresh_token',
+                    client_id: clientId,
+                    refresh_token: refreshToken,
+                }),
+            });
+
+            if (!response.ok) {
+                logger.warn(`token refresh failed: ${response.status} ${response.statusText}`);
+                // Retry in 30 seconds
+                setTimeout(() => refreshAccessToken(refreshToken), 30_000);
+                return;
+            }
+
+            const tokens = await response.json() as {
+                access_token: string;
+                refresh_token?: string;
+                expires_in: number;
+            };
+
+            if (currentAuthInfo) {
+                currentAuthInfo.token = tokens.access_token;
+                logger.info(`access token refreshed for "${currentAuthInfo.user}"`);
+            }
+
+            // Auth0 may rotate the refresh token — use the new one if provided
+            scheduleRefresh(tokens.refresh_token ?? refreshToken, tokens.expires_in);
+        } catch (err) {
+            logger.warn(`token refresh error: ${err}`);
+            setTimeout(() => refreshAccessToken(refreshToken), 30_000);
+        }
+    };
+
+    const scheduleRefresh = (refreshToken: string, expiresIn: number) => {
+        // Refresh 60 seconds before expiry, minimum 10 seconds
+        const refreshMs = Math.max((expiresIn - 60) * 1000, 10_000);
+        logger.info(`scheduling token refresh in ${Math.round(refreshMs / 1000)}s`);
+        setTimeout(() => refreshAccessToken(refreshToken), refreshMs);
+    };
+
     logger.info(`auth0 login endpoint registered on [${loginUrlPath}]`);
     logger.info(`auth0 callback endpoint registered on [${loginCallbackPath}]`);
 
     handle(
         // ---------------------------------------------------------------
-        // GET /login/auth0 — redirect to Auth0 Universal Login
+        // GET /login/auth0 — redirect to Auth0 with PKCE challenge
         // ---------------------------------------------------------------
         {
             request: { method: 'GET', path: loginUrlPath },
@@ -51,19 +117,27 @@ export const app = async (
 
                 const nonce = randomUUID();
                 const state = randomUUID();
+                const codeVerifier = generateCodeVerifier();
+                const codeChallenge = generateCodeChallenge(codeVerifier);
                 const redirectUri = `${request.protocol}://${request.host}${loginCallbackPath}`;
-                logger.info(`initiating Auth0 implicit login flow ${redirectUri}`);
+
+                // Store PKCE verifier for the callback
+                pendingCodeVerifier = codeVerifier;
+                pendingRedirectUri = redirectUri;
+
+                logger.info(`initiating Auth0 authorization code + PKCE flow → ${redirectUri}`);
 
                 const authorizeUrl = `${issuerUrl}/authorize?` + new URLSearchParams({
-                    response_type: 'id_token token',
+                    response_type: 'code',
                     response_mode: 'form_post',
                     client_id: clientId,
                     redirect_uri: redirectUri,
                     scope: scopes,
                     state,
                     nonce,
                     audience: config.audience ?? `io.bridge`,
-
+                    code_challenge: codeChallenge,
+                    code_challenge_method: 'S256',
                 }).toString();
 
                 logger.info(`redirecting to Auth0: ${authorizeUrl}`);
@@ -73,7 +147,8 @@ export const app = async (
             }
         },
         // ---------------------------------------------------------------
-        // POST /login/oauth2/code/auth0 — Auth0 posts tokens here
+        // POST /login/oauth2/code/auth0 — Auth0 posts authorization code;
+        //       exchange it for access, id & refresh tokens
         // ---------------------------------------------------------------
         {
             request: { method: 'POST', path: loginCallbackPath },
@@ -94,22 +169,81 @@ export const app = async (
                     return;
                 }
 
-                const idToken = formData.get('id_token');
+                const code = formData.get('code');
+                if (!code || !pendingCodeVerifier || !pendingRedirectUri) {
+                    logger.warn('missing authorization code or PKCE verifier');
+                    response.setRawStatusCode(400);
+                    await response.body(new TextEncoder().encode(
+                        'Missing authorization code or PKCE verifier. Please retry login.'
+                    ));
+                    await response.end();
+                    return;
+                }
+
+                // Exchange the authorization code for tokens
+                const codeVerifier = pendingCodeVerifier;
+                const redirectUri = pendingRedirectUri;
+                pendingCodeVerifier = undefined;
+                pendingRedirectUri = undefined;
+
+                const tokenResponse = await fetch(`${issuerUrl}/oauth/token`, {
+                    method: 'POST',
+                    headers: { 'Content-Type': 'application/json' },
+                    body: JSON.stringify({
+                        grant_type: 'authorization_code',
+                        client_id: clientId,
+                        code_verifier: codeVerifier,
+                        code,
+                        redirect_uri: redirectUri,
+                    }),
+                });
+
+                if (!tokenResponse.ok) {
+                    const errorBody = await tokenResponse.text();
+                    logger.warn(`token exchange failed: ${tokenResponse.status} — ${errorBody}`);
+                    response.setRawStatusCode(400);
+                    await response.body(new TextEncoder().encode(
+                        `Token exchange failed: ${errorBody}`
+                    ));
+                    await response.end();
+                    return;
+                }
+
+                const tokens = await tokenResponse.json() as {
+                    access_token: string;
+                    id_token?: string;
+                    refresh_token?: string;
+                    expires_in: number;
+                };
+
                 let user = 'dev-user';
                 let username;
-                if (idToken) {
-                    const payload = JSON.parse(Buffer.from(idToken.split('.')[1], 'base64').toString());
+                if (tokens.id_token) {
+                    const payload = JSON.parse(Buffer.from(tokens.id_token.split('.')[1], 'base64').toString());
                     user = payload.email;
                     username = payload.name;
                 }
                 username ??= user;
 
-                // set authInfo with the received tokens and user
-                config.authInfoResolver({
-                    token: formData.get('access_token'),
+                // Resolve the auth info promise (consumed by gateway mesh config)
+                const authInfo: AuthInfo = {
+                    token: tokens.access_token,
                     user,
                     username
-                });
+                };
+                currentAuthInfo = authInfo;
+                config.authInfoResolver(authInfo);
+
+                // Schedule automatic token refresh if we received a refresh token
+                if (tokens.refresh_token && tokens.expires_in) {
+                    scheduleRefresh(tokens.refresh_token, tokens.expires_in);
+                } else {
+                    logger.warn(
+                        'no refresh token received — token will not auto-renew. ' +
+                        'Ensure the Auth0 API has "Allow Offline Access" enabled and the ' +
+                        '"offline_access" scope is requested.'
+                    );
+                }
 
                 response.setRawStatusCode(200);
                 response.headers.set('Content-Type', 'text/html');

office/auth0/readme.md

@@ -19,7 +19,10 @@ The API represents the resource that tokens will be issued for — in this case,
    - **Identifier (Audience)**: `io.bridge` (this is the logical identifier, not a URL — it must match `IO_BRIDGE_SERVER_AUTH_OAUTH2_JWT_AUDIENCE` in your `.env`)
    - **Signing Algorithm**: `RS256` (default)
 4. Click **Create**.
-5. Note the **Identifier** value — this is your **audience**.
+5. Go to the **Settings** tab of the newly created API.
+6. Enable **Allow Offline Access** — this allows the desktop gateway to request a refresh token (via the `offline_access` scope) so it can automatically renew expired access tokens without requiring the user to log in again.
+7. Click **Save**.
+8. Note the **Identifier** value — this is your **audience**.
 
 ### Configuration mapping
 
@@ -29,7 +32,7 @@ The API represents the resource that tokens will be issued for — in this case,
 
 ## 3. Create a Single-Page Application (SPA)
 
-The SPA application is used by both the **browser platform** (via `@auth0/auth0-react`) and the **desktop gateway** (via the implicit flow callback registered in `auth0/app.ts`).
+The SPA application is used by both the **browser platform** (via `@auth0/auth0-react`) and the **desktop gateway** (via the Authorization Code + PKCE flow registered in `auth0/app.ts`).
 
 1. In the Auth0 Dashboard navigate to **Applications → Applications**.
 2. Click **+ Create Application**.
@@ -39,6 +42,7 @@ The SPA application is used by both the **browser platform** (via `@auth0/auth0-
 4. Click **Create**.
 5. Go to the **Settings** tab of the newly created application.
 6. Note the **Client ID** and **Domain** — you will need them for `.env`.
+7. Go to the **APIs** tab and find the **io.Bridge** API (created in step 2). Enable **User access** (Authorization Code) — this authorizes the application to request tokens for the io.Bridge API on behalf of users.
 
 ### 3.1. Configure Callback URLs and Web Origins
 
@@ -54,7 +58,7 @@ http://localhost:5173,
 https://<your-github-pages-domain>
 ```
 
-- `http://localhost:8385/login/oauth2/code/auth0` — the desktop gateway's Auth0 callback endpoint (implicit flow with `response_mode=form_post`)
+- `http://localhost:8385/login/oauth2/code/auth0` — the desktop gateway's Auth0 callback endpoint (authorization code + PKCE with `response_mode=form_post`)
 - `http://localhost:5173` — the Vite dev server (browser platform login)
 - Add any additional deployed URLs (e.g. GitHub Pages) as needed
 
@@ -197,9 +201,25 @@ VITE_AUTH0_AUDIENCE=io.bridge
 On startup, the **desktop gateway** (`gateway-server.config.ts`) probes the bridge by sending `POST <bridge_url>/api/nodes` with an empty JSON array:
 
 - **2xx response** → no authentication required; the gateway proceeds with the local OS username.
-- **401 + `WWW-Authenticate: Bearer`** → authentication is required; the gateway registers the Auth0 login and callback routes (`/login/auth0` and `/login/oauth2/code/auth0`), then opens the login page in the system browser. After the user authenticates, Auth0 posts the tokens back to the callback endpoint. The received access token is then used for the mesh connection to io.Bridge.
+- **401 + `WWW-Authenticate: Bearer`** → authentication is required; the gateway starts the Authorization Code + PKCE flow (see below).
 - **Other / unreachable** → the gateway logs a warning and proceeds without a token (the mesh will retry once the bridge becomes available).
 
+### Authorization Code + PKCE flow
+
+When authentication is required, the gateway:
+
+1. Generates a **PKCE code verifier** and its SHA-256 **code challenge**.
+2. Registers login (`/login/auth0`) and callback (`/login/oauth2/code/auth0`) routes on the local HTTP server.
+3. Opens the Auth0 Universal Login page in the system browser with `response_type=code`, `response_mode=form_post`, and the PKCE challenge.
+4. After the user authenticates, Auth0 POSTs the **authorization code** back to the callback endpoint.
+5. The gateway exchanges the code (plus the PKCE verifier) for **access, ID, and refresh tokens** via `POST <issuerUrl>/oauth/token`.
+6. The access token is used immediately for the mesh connection to io.Bridge.
+7. A timer is scheduled to **refresh the access token** automatically (60 seconds before expiry) using the refresh token — so the gateway stays connected without requiring the user to log in again.
+
+> **Note:** The `offline_access` scope and the API's **Allow Offline Access** setting (step 2.6) are both required for the refresh token to be issued.
+
+> **Tip:** To test the refresh logic without waiting 24 hours, go to **Applications → APIs → io.Bridge → Settings** and lower both **Token Expiration (Seconds)** and **Token Expiration For Browser Flows (Seconds)** to the same value (e.g. `120` for 2 minutes) — the browser flow lifetime cannot exceed the maximum. The gateway refreshes 60 seconds before expiry. Remember to restore reasonable values afterwards.
+
 The **browser platform** (`App.tsx`) uses `@auth0/auth0-react` with the `IOConnectHome` login type set to `"auth0"`, handling authentication entirely client-side.
 
 

office/gateway-server.config.ts

@@ -21,7 +21,7 @@ catch (e) {
     }
 }
 
-const BRIDGE_URL = process.env["VITE_IO_BRIDGE_URL"] ?? "https://gw-bridge-examples.interop.io";
+const BRIDGE_URL = process.env["IO_GATEWAY_BRIDGE_URL"] ?? process.env["VITE_IO_BRIDGE_URL"] ?? "https://gw-bridge-examples.interop.io";
 
 let authInfoResolver: (data: AuthInfo) => void;
 const authInfoPromise: Promise<AuthInfo> = new Promise((resolve) => {
@@ -190,9 +190,9 @@ export default defineConfig({
 
         // 2b. Auth required (or bridge unreachable — fall back to auth if
         //     configured, so mesh can connect once bridge becomes available).
-        const issuerUrl = process.env["IO_BRIDGE_SERVER_AUTH_OAUTH2_JWT_ISSUERURI"] ?? `https://${process.env["VITE_AUTH0_DOMAIN"]}`;
-        const clientId = process.env["VITE_AUTH0_CLIENT_ID"];
-        const audience = process.env["IO_BRIDGE_SERVER_AUTH_OAUTH2_JWT_AUDIENCE"] ?? process.env["VITE_AUTH0_AUDIENCE"];
+        const issuerUrl = process.env["IO_GATEWAY_AUTH_ISSUERURI"] ?? process.env["IO_BRIDGE_SERVER_AUTH_OAUTH2_JWT_ISSUERURI"] ?? `https://${process.env["VITE_AUTH0_DOMAIN"]}`;
+        const clientId = process.env["IO_GATEWAY_AUTH_CLIENT_ID"] ?? process.env["VITE_AUTH0_CLIENT_ID"];
+        const audience = process.env["IO_GATEWAY_AUTH_AUDIENCE"] ?? process.env["IO_BRIDGE_SERVER_AUTH_OAUTH2_JWT_AUDIENCE"] ?? process.env["VITE_AUTH0_AUDIENCE"];
 
         if (!issuerUrl || !clientId || !audience) {
             if (authResult === "required") {
@@ -223,7 +223,7 @@ export default defineConfig({
                 issuerUrl,
                 clientId,
                 audience,
-                scopes: process.env.VITE_AUTH0_SCOPES ?? "openid email",
+                scope: process.env.IO_GATEWAY_AUTH0_SCOPE,
             },
             configurer,
         );