@agentforge-io/sdk-console 0.1.0 → 0.2.0

package/README.md

@@ -76,11 +76,33 @@ On web, `MemoryTokenStore` (exported) or a `localStorage`-backed store works the
 | `onSignedOut(reason)` | `'refresh_rejected' \| 'no_refresh_token'`. |
 | `defaultHeaders` | Extra headers on every call. Any non-simple header makes browsers preflight. |
 | `timeoutMs` | Default 30000; `0` disables. Timeouts reject as `ApiError` with `status: 0`, `code: 'timeout'`. |
+| `crypto` | `OAuthCrypto` `{ getRandomValues(bytes), sha256(data) }` for OAuth PKCE where there is no global WebCrypto (React Native: wrap `expo-crypto`). |
 | `maxRateLimitRetries` | GET replays on 429 honouring `Retry-After` (default 2). Writes are never replayed. |
 
 A refresh that fails because of the network (offline, 5xx) does **not** sign the user out:
 the original 401 is thrown and the session is kept.
 
+## OAuth sign-in (Google / GitHub)
+
+```ts
+const { url, codeVerifier } = await af.auth.oauthStart('google', { returnTo: 'poodleck-console://auth/callback' });
+// open `url` in the browser; keep `codeVerifier` until the redirect comes back
+const ret = parseOAuthReturn(redirectUrl); // { code } | { error } | null
+if (ret && 'code' in ret) await af.auth.oauthComplete({ code: ret.code, codeVerifier });
+```
+
+`returnTo` must be in the server allow-list (400 `return_to_not_allowed`), and the
+server requires the PKCE challenge (400 `pkce_required`). A bad / expired / reused
+code answers 400 `invalid_grant`. On React Native pass the `crypto` option:
+
+```ts
+import * as Crypto from 'expo-crypto';
+new ConsoleClient({ ..., crypto: {
+  getRandomValues: (b) => Crypto.getRandomValues(b),
+  sha256: async (d) => new Uint8Array(await Crypto.digest(Crypto.CryptoDigestAlgorithm.SHA256, d)),
+} });
+```
+
 ## Errors
 
 Every failure rejects with `ApiError`: `status` (0 = no response: `network_error` or
@@ -100,7 +122,7 @@ Resource → methods → HTTP route (all JSON, bearer auth unless marked *public
 | | `me` | `GET /auth/me` |
 | | `completeOnboarding` / `reopenOnboarding` | `POST /auth/me/onboarding/complete` · `.../reopen` |
 | | `strategies` (public) | `GET /auth/strategies` |
-| `tenants` | `listMine` | `GET /me/tenants` |
+| | `oauthStart` (no request) / `oauthComplete` (public, stores session) | URL `GET /auth/:provider?returnTo=&codeChallenge=` · `POST /auth/oauth/exchange` || `tenants` | `listMine` | `GET /me/tenants` |
 | | `create` / `update` | `POST /admin/tenants` · `PATCH /admin/tenants/:id` |
 | `t.members` | `list` / `add` | `GET` / `POST :T/members` |
 | | `updateRole` / `remove` | `PATCH` / `DELETE :T/members/:membershipId` |
@@ -138,7 +160,7 @@ Resource → methods → HTTP route (all JSON, bearer auth unless marked *public
 ## Not covered (yet)
 
 No `tenants.get` (the server has no `GET /admin/tenants/:id`: read it from `listMine`),
-native Google/GitHub sign-in (the OAuth routes are browser redirects), password
+password
 reset / email verification, Apps write operations, template pricing and earnings,
 skills, trace/activity, the AI designer. They are tracked in the Console SDD.
 

package/dist/http.d.ts

@@ -1,3 +1,4 @@
+import type { OAuthCrypto } from './oauth';
 import type { AuthTokens, TokenStore } from './token-store';
 export type FetchLike = (input: string, init?: RequestInit) => Promise<Response>;
 /** Why the session ended without the user asking for it. */
@@ -20,6 +21,10 @@ export interface ConsoleClientOptions {
     timeoutMs?: number;
     /** Replays of a GET answered 429, honouring `Retry-After`. Default 2. */
     maxRateLimitRetries?: number;
+    /** Crypto adapter for OAuth PKCE (`auth.oauthStart`). Only needed where there
+     *  is no global WebCrypto (`crypto.getRandomValues` + `crypto.subtle.digest`),
+     *  i.e. React Native: pass an `expo-crypto` based one. */
+    crypto?: OAuthCrypto;
     /** Sleep used between 429 replays. Injectable for tests. */
     sleep?: (ms: number) => Promise<void>;
 }
@@ -37,6 +42,7 @@ export declare function buildQuery(query?: Record<string, QueryValue>): string;
 export declare function seg(value: string): string;
 export declare class HttpCore {
     readonly baseURL: string;
+    readonly crypto?: OAuthCrypto;
     private readonly store;
     private readonly opts;
     private refreshing;

package/dist/http.js

@@ -47,6 +47,7 @@ class HttpCore {
         this.opts = opts;
         this.baseURL = opts.baseURL.replace(/\/+$/, '');
         this.store = opts.tokenStore;
+        this.crypto = opts.crypto;
     }
     /** Authenticated (or `auth: false`) JSON request. Resolves `undefined` on 204 / empty body. */
     async request(method, path, options = {}) {

package/dist/index.d.ts

@@ -2,6 +2,8 @@ export { ConsoleClient, TenantScope } from './client';
 export { ApiError, isApiError } from './errors';
 export { MemoryTokenStore } from './token-store';
 export type { AuthTokens, MaybePromise, TokenStore } from './token-store';
+export { parseOAuthReturn } from './oauth';
+export type { OAuthCrypto, OAuthReturn } from './oauth';
 export type { ConsoleClientOptions, FetchLike, QueryValue, RequestOptions, SignedOutReason } from './http';
 export * from './types';
 export { AgentsResource, ChatTokensResource } from './resources/agents';

package/dist/index.js

@@ -14,7 +14,7 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.VariablesResource = exports.ToolsResource = exports.TenantsResource = exports.TenantTemplatesResource = exports.TemplatesResource = exports.TeamsResource = exports.TeamHumanMembersResource = exports.PlaygroundResource = exports.MarketplaceResource = exports.PublicInvitesResource = exports.MembersResource = exports.InvitesResource = exports.ConnectorsResource = exports.AuthResource = exports.AppsResource = exports.ChatTokensResource = exports.AgentsResource = exports.MemoryTokenStore = exports.isApiError = exports.ApiError = exports.TenantScope = exports.ConsoleClient = void 0;
+exports.VariablesResource = exports.ToolsResource = exports.TenantsResource = exports.TenantTemplatesResource = exports.TemplatesResource = exports.TeamsResource = exports.TeamHumanMembersResource = exports.PlaygroundResource = exports.MarketplaceResource = exports.PublicInvitesResource = exports.MembersResource = exports.InvitesResource = exports.ConnectorsResource = exports.AuthResource = exports.AppsResource = exports.ChatTokensResource = exports.AgentsResource = exports.parseOAuthReturn = exports.MemoryTokenStore = exports.isApiError = exports.ApiError = exports.TenantScope = exports.ConsoleClient = void 0;
 var client_1 = require("./client");
 Object.defineProperty(exports, "ConsoleClient", { enumerable: true, get: function () { return client_1.ConsoleClient; } });
 Object.defineProperty(exports, "TenantScope", { enumerable: true, get: function () { return client_1.TenantScope; } });
@@ -23,6 +23,8 @@ Object.defineProperty(exports, "ApiError", { enumerable: true, get: function ()
 Object.defineProperty(exports, "isApiError", { enumerable: true, get: function () { return errors_1.isApiError; } });
 var token_store_1 = require("./token-store");
 Object.defineProperty(exports, "MemoryTokenStore", { enumerable: true, get: function () { return token_store_1.MemoryTokenStore; } });
+var oauth_1 = require("./oauth");
+Object.defineProperty(exports, "parseOAuthReturn", { enumerable: true, get: function () { return oauth_1.parseOAuthReturn; } });
 __exportStar(require("./types"), exports);
 var agents_1 = require("./resources/agents");
 Object.defineProperty(exports, "AgentsResource", { enumerable: true, get: function () { return agents_1.AgentsResource; } });

package/dist/oauth.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Minimal crypto surface needed for PKCE. Pass it as the `crypto` client option
+ * on runtimes without a global WebCrypto (React Native). With `expo-crypto`:
+ *
+ *   crypto: {
+ *     getRandomValues: (bytes) => Crypto.getRandomValues(bytes),
+ *     sha256: async (data) => new Uint8Array(await Crypto.digest(Crypto.CryptoDigestAlgorithm.SHA256, data)),
+ *   }
+ */
+export interface OAuthCrypto {
+    /** Fill `bytes` with cryptographically secure random values. May fill in
+     *  place (return nothing) or return the filled array. */
+    getRandomValues(bytes: Uint8Array): Uint8Array | void;
+    /** SHA-256 digest (32 bytes) of `data`. */
+    sha256(data: Uint8Array): Promise<Uint8Array>;
+}
+export declare const CODE_VERIFIER_LENGTH = 64;
+/** Resolve the adapter, falling back to the global WebCrypto. Throws if neither exists. */
+export declare function resolveCrypto(adapter?: OAuthCrypto): OAuthCrypto;
+/** RFC 7636 verifier: 64 chars of the unreserved set. */
+export declare function generateCodeVerifier(c: OAuthCrypto): string;
+export declare function base64UrlEncode(bytes: Uint8Array): string;
+/** S256 challenge: base64url(SHA-256(ASCII(verifier))), no padding. */
+export declare function codeChallengeS256(c: OAuthCrypto, verifier: string): Promise<string>;
+/** Result of `parseOAuthReturn`. */
+export type OAuthReturn = {
+    code: string;
+} | {
+    error: string;
+};
+/**
+ * Read the fragment of the URL the server redirected to: `#code=...` on
+ * success, `#error=...` on failure. Works for `https://` and custom schemes
+ * (`poodleck-console://auth/callback#code=...`). Returns `null` when the URL
+ * carries neither. If both are present, `error` wins.
+ */
+export declare function parseOAuthReturn(url: string): OAuthReturn | null;

package/dist/oauth.js

@@ -0,0 +1,97 @@
+"use strict";
+// OAuth browser-redirect sign-in helpers (PKCE, RFC 7636). Pure and runtime
+// agnostic: no Node `crypto`, no Buffer, no TextEncoder, no URLSearchParams, so
+// it runs on Hermes / React Native, browsers and Node >= 19.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CODE_VERIFIER_LENGTH = void 0;
+exports.resolveCrypto = resolveCrypto;
+exports.generateCodeVerifier = generateCodeVerifier;
+exports.base64UrlEncode = base64UrlEncode;
+exports.codeChallengeS256 = codeChallengeS256;
+exports.parseOAuthReturn = parseOAuthReturn;
+const UNRESERVED = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-._~';
+const B64URL = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_';
+/** Largest multiple of 66 below 256: bytes at or above it are rejected (no modulo bias). */
+const REJECT_FROM = 198;
+exports.CODE_VERIFIER_LENGTH = 64;
+/** Resolve the adapter, falling back to the global WebCrypto. Throws if neither exists. */
+function resolveCrypto(adapter) {
+    if (adapter)
+        return adapter;
+    const g = globalThis.crypto;
+    if (g && typeof g.getRandomValues === 'function' && g.subtle && typeof g.subtle.digest === 'function') {
+        return {
+            getRandomValues: (bytes) => g.getRandomValues(bytes),
+            sha256: async (data) => new Uint8Array(await g.subtle.digest('SHA-256', data)),
+        };
+    }
+    throw new Error('No crypto available for OAuth PKCE: pass a `crypto` adapter ({ getRandomValues, sha256 }) in the client options');
+}
+function randomBytes(c, length) {
+    const bytes = new Uint8Array(length);
+    return c.getRandomValues(bytes) ?? bytes;
+}
+/** RFC 7636 verifier: 64 chars of the unreserved set. */
+function generateCodeVerifier(c) {
+    let out = '';
+    while (out.length < exports.CODE_VERIFIER_LENGTH) {
+        const bytes = randomBytes(c, exports.CODE_VERIFIER_LENGTH * 2);
+        for (let i = 0; i < bytes.length && out.length < exports.CODE_VERIFIER_LENGTH; i++) {
+            if (bytes[i] < REJECT_FROM)
+                out += UNRESERVED[bytes[i] % UNRESERVED.length];
+        }
+    }
+    return out;
+}
+function base64UrlEncode(bytes) {
+    let out = '';
+    for (let i = 0; i < bytes.length; i += 3) {
+        const n = (bytes[i] << 16) | ((bytes[i + 1] ?? 0) << 8) | (bytes[i + 2] ?? 0);
+        out += B64URL[(n >> 18) & 63] + B64URL[(n >> 12) & 63];
+        if (i + 1 < bytes.length)
+            out += B64URL[(n >> 6) & 63];
+        if (i + 2 < bytes.length)
+            out += B64URL[n & 63];
+    }
+    return out;
+}
+/** S256 challenge: base64url(SHA-256(ASCII(verifier))), no padding. */
+async function codeChallengeS256(c, verifier) {
+    const data = new Uint8Array(verifier.length);
+    for (let i = 0; i < verifier.length; i++)
+        data[i] = verifier.charCodeAt(i) & 0xff;
+    const digest = await c.sha256(data);
+    return base64UrlEncode(digest);
+}
+/**
+ * Read the fragment of the URL the server redirected to: `#code=...` on
+ * success, `#error=...` on failure. Works for `https://` and custom schemes
+ * (`poodleck-console://auth/callback#code=...`). Returns `null` when the URL
+ * carries neither. If both are present, `error` wins.
+ */
+function parseOAuthReturn(url) {
+    if (typeof url !== 'string')
+        return null;
+    const hash = url.indexOf('#');
+    if (hash < 0)
+        return null;
+    const params = {};
+    for (const pair of url.slice(hash + 1).split('&')) {
+        if (!pair)
+            continue;
+        const eq = pair.indexOf('=');
+        const rawKey = eq < 0 ? pair : pair.slice(0, eq);
+        const rawVal = eq < 0 ? '' : pair.slice(eq + 1);
+        try {
+            params[decodeURIComponent(rawKey.replace(/\+/g, ' '))] = decodeURIComponent(rawVal.replace(/\+/g, ' '));
+        }
+        catch {
+            // malformed escape: skip this pair
+        }
+    }
+    if (params.error)
+        return { error: params.error };
+    if (params.code)
+        return { code: params.code };
+    return null;
+}

package/dist/resources/auth.d.ts

@@ -1,4 +1,4 @@
-import type { HttpCore } from '../http';
+import { type HttpCore } from '../http';
 import type { AuthResult, AuthStrategies, AuthUser, LoginInput, RegisterInput } from '../types';
 export declare class AuthResource {
     private readonly http;
@@ -8,6 +8,27 @@ export declare class AuthResource {
     /** `POST /auth/login`. Stores the session. 403 `captcha_failed` when the
      *  server enforces Turnstile and no `captchaToken` was sent. */
     login(input: LoginInput): Promise<AuthResult>;
+    /**
+     * Start a browser OAuth sign-in (PKCE). Builds `GET /auth/:provider?returnTo=&codeChallenge=`
+     * (no network call): open `url` in the browser, keep `codeVerifier` (in
+     * memory / sessionStorage), and when the browser lands on `returnTo#code=...`
+     * call `oauthComplete`. `returnTo` must be in the server allow-list, else
+     * opening `url` answers 400 `return_to_not_allowed`. Needs a global WebCrypto
+     * or the `crypto` client option; throws otherwise.
+     */
+    oauthStart(provider: 'google' | 'github' | (string & {}), input: {
+        returnTo: string;
+    }): Promise<{
+        url: string;
+        codeVerifier: string;
+    }>;
+    /** `POST /auth/oauth/exchange` (public): trade the one-time `code` from the
+     *  redirect + the `codeVerifier` from `oauthStart` for a session. Stores it
+     *  like `login`. 400 `invalid_grant` when expired, reused or mismatched. */
+    oauthComplete(input: {
+        code: string;
+        codeVerifier: string;
+    }): Promise<AuthResult>;
     /** `POST /auth/refresh` with the stored refresh token (single-flight with
      *  the automatic refresh). Rotates and stores the new pair. Not needed in
      *  normal use: a 401 refreshes by itself. */

package/dist/resources/auth.js

@@ -3,6 +3,8 @@
 // touch them. Routes: apps/server identity AuthController / OAuthController.
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.AuthResource = void 0;
+const http_1 = require("../http");
+const oauth_1 = require("../oauth");
 class AuthResource {
     constructor(http) {
         this.http = http;
@@ -20,6 +22,34 @@ class AuthResource {
         await this.http.setSession(res);
         return res;
     }
+    /**
+     * Start a browser OAuth sign-in (PKCE). Builds `GET /auth/:provider?returnTo=&codeChallenge=`
+     * (no network call): open `url` in the browser, keep `codeVerifier` (in
+     * memory / sessionStorage), and when the browser lands on `returnTo#code=...`
+     * call `oauthComplete`. `returnTo` must be in the server allow-list, else
+     * opening `url` answers 400 `return_to_not_allowed`. Needs a global WebCrypto
+     * or the `crypto` client option; throws otherwise.
+     */
+    async oauthStart(provider, input) {
+        if (!input?.returnTo)
+            throw new Error('returnTo is required');
+        const crypto = (0, oauth_1.resolveCrypto)(this.http.crypto);
+        const codeVerifier = (0, oauth_1.generateCodeVerifier)(crypto);
+        const codeChallenge = await (0, oauth_1.codeChallengeS256)(crypto, codeVerifier);
+        const query = (0, http_1.buildQuery)({ returnTo: input.returnTo, codeChallenge });
+        return { url: `${this.http.baseURL}/auth/${(0, http_1.seg)(provider)}${query}`, codeVerifier };
+    }
+    /** `POST /auth/oauth/exchange` (public): trade the one-time `code` from the
+     *  redirect + the `codeVerifier` from `oauthStart` for a session. Stores it
+     *  like `login`. 400 `invalid_grant` when expired, reused or mismatched. */
+    async oauthComplete(input) {
+        const res = await this.http.request('POST', '/auth/oauth/exchange', {
+            body: { code: input.code, codeVerifier: input.codeVerifier },
+            auth: false,
+        });
+        await this.http.setSession(res);
+        return res;
+    }
     /** `POST /auth/refresh` with the stored refresh token (single-flight with
      *  the automatic refresh). Rotates and stores the new pair. Not needed in
      *  normal use: a 401 refreshes by itself. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentforge-io/sdk-console",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "User-session SDK for admin clients of the AgentForge platform (Expo / React Native, web, Node). Dashboard JWT auth with refresh, tenant scoping, typed resources.",
   "license": "MIT",
   "repository": {