poe-code 4.0.19 → 4.0.21

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "poe-code",
-  "version": "4.0.19",
+  "version": "4.0.21",
   "description": "CLI tool to configure Poe API for developer workflows.",
   "license": "MIT",
   "type": "module",
@@ -19,6 +19,10 @@
       "types": "./dist/agent.d.ts",
       "import": "./dist/agent.js"
     },
+    "./credentials": {
+      "types": "./dist/credentials.d.ts",
+      "import": "./dist/credentials.js"
+    },
     "./skills": {
       "types": "./dist/skills.d.ts",
       "import": "./dist/skills.js"

package/packages/poe-oauth/dist/index.d.ts

@@ -1,5 +1,8 @@
 export { checkAuth } from "./check-auth.js";
-export { createOAuthClient } from "./oauth-client.js";
+export { createOAuthAuthorizationUrl, createOAuthClient, exchangeOAuthCode } from "./oauth-client.js";
+export { validateOAuthAuthorizationCallback } from "./loopback-authorization.js";
+export { generateCodeChallenge, generateCodeVerifier } from "./pkce.js";
 export type { OAuthLandingPage } from "./loopback-authorization.js";
 export type { AuthIdentity, CheckAuthOptions } from "./check-auth.js";
-export type { OAuthClient, OAuthClientConfig, OAuthResult, OAuthAuthorization } from "./oauth-client.js";
+export type { OAuthClient, OAuthClientConfig, OAuthResult, OAuthAuthorization, CreateOAuthAuthorizationUrlOptions, ExchangeOAuthCodeOptions } from "./oauth-client.js";
+export type { ValidateOAuthAuthorizationCallbackOptions } from "./loopback-authorization.js";

package/packages/poe-oauth/dist/index.js

@@ -1,2 +1,4 @@
 export { checkAuth } from "./check-auth.js";
-export { createOAuthClient } from "./oauth-client.js";
+export { createOAuthAuthorizationUrl, createOAuthClient, exchangeOAuthCode } from "./oauth-client.js";
+export { validateOAuthAuthorizationCallback } from "./loopback-authorization.js";
+export { generateCodeChallenge, generateCodeVerifier } from "./pkce.js";

package/packages/poe-oauth/dist/loopback-authorization.d.ts

@@ -15,6 +15,13 @@ export interface LoopbackAuthorizationSession {
     waitForCode(authorizationUrl: string): Promise<string>;
     close(): void;
 }
+export interface ValidateOAuthAuthorizationCallbackOptions {
+    callbackUrl: string | URL;
+    expectedState: string;
+    expectedIssuer?: string;
+    requireIssuer?: boolean;
+}
+export declare function validateOAuthAuthorizationCallback(options: ValidateOAuthAuthorizationCallbackOptions): string;
 export declare function createLoopbackAuthorizationSession(options?: LoopbackAuthorizationOptions): Promise<LoopbackAuthorizationSession>;
 export declare function extractCodeFromInput(input: string): string | null;
 export declare function buildSuccessPage(landingPage?: OAuthLandingPage): string;

package/packages/poe-oauth/dist/loopback-authorization.js

@@ -1,5 +1,39 @@
 import http from "node:http";
 import { parseAuthorizationState } from "./authorization-state.js";
+export function validateOAuthAuthorizationCallback(options) {
+    let url;
+    try {
+        url = typeof options.callbackUrl === "string"
+            ? new URL(options.callbackUrl)
+            : options.callbackUrl;
+    }
+    catch {
+        throw new Error("Poe OAuth callbackUrl must be an absolute URL.");
+    }
+    const callback = {
+        code: url.searchParams.get("code"),
+        state: url.searchParams.get("state"),
+        iss: url.searchParams.get("iss")
+    };
+    const expected = {
+        state: validateExpectedState(options.expectedState),
+        issuer: options.expectedIssuer ?? null,
+        requireIssuer: options.requireIssuer ?? false
+    };
+    validateAuthorizationCallbackBinding(callback, expected);
+    const authorizationError = url.searchParams.get("error");
+    if (authorizationError !== null) {
+        const description = url.searchParams.get("error_description");
+        const safeError = sanitizeAuthorizationError(authorizationError, expected.state);
+        const safeDescription = description === null
+            ? null
+            : sanitizeAuthorizationError(description, expected.state);
+        throw new Error(safeDescription === null
+            ? `OAuth authorization failed: ${safeError}`
+            : `OAuth authorization failed: ${safeError} — ${safeDescription}`);
+    }
+    return validateAuthorizationCallbackParameters(callback, expected);
+}
 export async function createLoopbackAuthorizationSession(options = {}) {
     const callbackPath = options.callbackPath ?? "/callback";
     const server = options.createServer ? options.createServer() : http.createServer();
@@ -46,39 +80,26 @@ function waitForAuthorizationCode(server, authorizationUrl, options, callbackPat
                 res.end("Not found");
                 return;
             }
-            const error = url.searchParams.get("error");
-            if (error !== null) {
-                try {
-                    validateAuthorizationCallbackBinding({
-                        state: url.searchParams.get("state"),
-                        iss: url.searchParams.get("iss")
-                    }, expectedAuthorization);
-                }
-                catch (validationError) {
-                    res.writeHead(400);
-                    res.end(validationError instanceof Error ? validationError.message : "Invalid OAuth callback");
-                    return;
-                }
-                const description = url.searchParams.get("error_description") ?? error;
-                res.writeHead(400);
-                res.end(`Authorization failed: ${description}`);
-                settle(() => reject(new Error(`OAuth authorization failed: ${error} — ${description}`)));
-                return;
-            }
             try {
-                const code = validateAuthorizationCallbackParameters({
-                    code: url.searchParams.get("code"),
-                    state: url.searchParams.get("state"),
-                    iss: url.searchParams.get("iss")
-                }, expectedAuthorization);
+                const code = validateOAuthAuthorizationCallback({
+                    callbackUrl: url,
+                    expectedState: expectedAuthorization.state ?? "",
+                    expectedIssuer: expectedAuthorization.issuer ?? undefined,
+                    requireIssuer: expectedAuthorization.requireIssuer
+                });
                 res.writeHead(200, { "Content-Type": "text/html" });
                 res.end(buildSuccessPage(options.landingPage));
                 settle(() => resolve(code));
             }
             catch (error) {
+                const validationError = error instanceof Error ? error : new Error(String(error));
                 res.writeHead(400);
-                res.end(error instanceof Error ? error.message : "Invalid OAuth callback");
-                settle(() => reject(error instanceof Error ? error : new Error(String(error))));
+                res.end(validationError.message);
+                if (url.searchParams.has("error") &&
+                    !validationError.message.startsWith("OAuth authorization failed:")) {
+                    return;
+                }
+                settle(() => reject(validationError));
             }
         });
         if (options.readLine !== undefined) {
@@ -171,6 +192,18 @@ function validateAuthorizationCallbackBinding(callback, expected) {
         throw new Error("OAuth callback issuer mismatch");
     }
 }
+function validateExpectedState(state) {
+    if (state.length === 0 || state.trim() !== state) {
+        throw new Error("Poe OAuth expectedState must not be blank or contain surrounding whitespace.");
+    }
+    return state;
+}
+function sanitizeAuthorizationError(value, expectedState) {
+    if (value.includes(expectedState)) {
+        return "authorization_error";
+    }
+    return value;
+}
 function escapeHtml(text) {
     return text
         .replaceAll("&", "&")

package/packages/poe-oauth/dist/oauth-client.d.ts

@@ -21,4 +21,21 @@ export interface OAuthAuthorization {
 export interface OAuthClient {
     authorize(): Promise<OAuthAuthorization>;
 }
+export interface CreateOAuthAuthorizationUrlOptions {
+    clientId: string;
+    redirectUri: string;
+    state: string;
+    codeChallenge: string;
+    authorizationEndpoint?: string;
+}
+export interface ExchangeOAuthCodeOptions {
+    clientId: string;
+    redirectUri: string;
+    code: string;
+    codeVerifier: string;
+    tokenEndpoint?: string;
+    fetch?: typeof globalThis.fetch;
+}
 export declare function createOAuthClient(config: OAuthClientConfig): OAuthClient;
+export declare function createOAuthAuthorizationUrl(options: CreateOAuthAuthorizationUrlOptions): string;
+export declare function exchangeOAuthCode(options: ExchangeOAuthCodeOptions): Promise<OAuthResult>;

package/packages/poe-oauth/dist/oauth-client.js

@@ -1,6 +1,6 @@
 import { createAuthorizationState } from "./authorization-state.js";
 import { createLoopbackAuthorizationSession } from "./loopback-authorization.js";
-import { generateCodeChallenge as generatePkceCodeChallenge, generateCodeVerifier as generatePkceCodeVerifier } from "./pkce.js";
+import { generateCodeChallenge as generatePkceCodeChallenge, generateCodeVerifier as generatePkceCodeVerifier, validateCodeChallenge, validateCodeVerifier } from "./pkce.js";
 const DEFAULT_AUTHORIZATION_ENDPOINT = "https://poe.com/oauth/authorize";
 const DEFAULT_TOKEN_ENDPOINT = "https://api.poe.com/token";
 const MAX_VALID_EPOCH_MS = 8_640_000_000_000_000;
@@ -9,7 +9,9 @@ export function createOAuthClient(config) {
     const clientId = validateClientId(config.clientId);
     const normalizedConfig = {
         ...config,
-        clientId
+        clientId,
+        authorizationEndpoint: validateHttpUrl(config.authorizationEndpoint ?? DEFAULT_AUTHORIZATION_ENDPOINT, "authorizationEndpoint"),
+        tokenEndpoint: validateHttpUrl(config.tokenEndpoint ?? DEFAULT_TOKEN_ENDPOINT, "tokenEndpoint")
     };
     return {
         authorize: () => startAuthorization(normalizedConfig, fetchFn)
@@ -33,8 +35,8 @@ async function startAuthorization(config, fetchFn) {
         }
     });
     const redirectUri = loopbackSession.redirectUri;
-    const authorizationUrl = buildAuthorizationUrl({
-        endpoint: authorizationEndpoint,
+    const authorizationUrl = createOAuthAuthorizationUrl({
+        authorizationEndpoint,
         clientId: config.clientId,
         redirectUri,
         codeChallenge,
@@ -48,13 +50,13 @@ async function startAuthorization(config, fetchFn) {
         resultPromise ??= (async () => {
             try {
                 const code = await loopbackSession.waitForCode(authorizationUrl);
-                return await exchangeCodeForApiKey({
+                return await exchangeOAuthCode({
                     tokenEndpoint,
                     code,
                     codeVerifier,
                     clientId: config.clientId,
                     redirectUri,
-                    fetchFn
+                    fetch: fetchFn
                 });
             }
             finally {
@@ -65,41 +67,63 @@ async function startAuthorization(config, fetchFn) {
     };
     return { authorizationUrl, waitForResult };
 }
-function buildAuthorizationUrl(params) {
-    const url = new URL(params.endpoint);
+export function createOAuthAuthorizationUrl(options) {
+    const clientId = validateClientId(options.clientId);
+    const redirectUri = validateHttpUrl(options.redirectUri, "redirectUri");
+    const state = validateOpaqueValue(options.state, "state");
+    const codeChallenge = validateCodeChallenge(options.codeChallenge);
+    const authorizationEndpoint = validateHttpUrl(options.authorizationEndpoint ?? DEFAULT_AUTHORIZATION_ENDPOINT, "authorizationEndpoint");
+    const url = new URL(authorizationEndpoint);
     url.searchParams.set("response_type", "code");
-    url.searchParams.set("client_id", params.clientId);
+    url.searchParams.set("client_id", clientId);
     url.searchParams.set("scope", "apikey:create");
-    url.searchParams.set("code_challenge", params.codeChallenge);
+    url.searchParams.set("code_challenge", codeChallenge);
     url.searchParams.set("code_challenge_method", "S256");
-    url.searchParams.set("redirect_uri", params.redirectUri);
-    url.searchParams.set("state", params.state);
+    url.searchParams.set("redirect_uri", redirectUri);
+    url.searchParams.set("state", state);
     return url.toString();
 }
-async function exchangeCodeForApiKey(params) {
+export async function exchangeOAuthCode(options) {
+    const clientId = validateClientId(options.clientId);
+    const redirectUri = validateHttpUrl(options.redirectUri, "redirectUri");
+    const code = validateOpaqueValue(options.code, "code");
+    const codeVerifier = validateCodeVerifier(options.codeVerifier);
+    const tokenEndpoint = validateHttpUrl(options.tokenEndpoint ?? DEFAULT_TOKEN_ENDPOINT, "tokenEndpoint");
+    const fetchFn = options.fetch ?? globalThis.fetch;
     const body = new URLSearchParams({
         grant_type: "authorization_code",
-        code: params.code,
-        code_verifier: params.codeVerifier,
-        client_id: params.clientId,
-        redirect_uri: params.redirectUri
-    });
-    const response = await params.fetchFn(params.tokenEndpoint, {
-        method: "POST",
-        headers: { "Content-Type": "application/x-www-form-urlencoded" },
-        body: body.toString()
+        code,
+        code_verifier: codeVerifier,
+        client_id: clientId,
+        redirect_uri: redirectUri
     });
+    let response;
+    try {
+        response = await fetchFn(tokenEndpoint, {
+            method: "POST",
+            headers: { "Content-Type": "application/x-www-form-urlencoded" },
+            body: body.toString()
+        });
+    }
+    catch {
+        throw new Error("Token exchange request failed");
+    }
     if (!response.ok) {
         const text = await response.text();
         const description = parseErrorDescription(text);
-        throw new Error(description ?? `Token exchange failed (${response.status}): ${text}`);
+        if (description !== null &&
+            !description.includes(codeVerifier) &&
+            !description.includes(code)) {
+            throw new Error(description);
+        }
+        throw new Error(`Token exchange failed (${response.status})`);
     }
     let value;
     try {
         value = (await response.json());
     }
     catch (error) {
-        throw new Error(`Token exchange failed: invalid JSON response from ${params.tokenEndpoint}`, {
+        throw new Error(`Token exchange failed: invalid JSON response from ${tokenEndpoint}`, {
             cause: error
         });
     }
@@ -157,6 +181,28 @@ function validateClientId(clientId) {
     }
     return clientId;
 }
+function validateHttpUrl(value, field) {
+    if (value.trim() !== value || value.length === 0) {
+        throw new Error(`Poe OAuth ${field} must be an absolute HTTP(S) URL.`);
+    }
+    let url;
+    try {
+        url = new URL(value);
+    }
+    catch {
+        throw new Error(`Poe OAuth ${field} must be an absolute HTTP(S) URL.`);
+    }
+    if ((url.protocol !== "https:" && url.protocol !== "http:") || url.hash.length > 0) {
+        throw new Error(`Poe OAuth ${field} must be an absolute HTTP(S) URL without a fragment.`);
+    }
+    return url.toString();
+}
+function validateOpaqueValue(value, field) {
+    if (value.length === 0 || value.trim() !== value) {
+        throw new Error(`Poe OAuth ${field} must not be blank or contain surrounding whitespace.`);
+    }
+    return value;
+}
 function isValidExpiresIn(value) {
     if (typeof value !== "number" ||
         !Number.isFinite(value) ||

package/packages/poe-oauth/dist/pkce.d.ts

@@ -1,2 +1,4 @@
 export declare function generateCodeVerifier(): string;
 export declare function generateCodeChallenge(verifier: string): string;
+export declare function validateCodeVerifier(verifier: string): string;
+export declare function validateCodeChallenge(challenge: string): string;

package/packages/poe-oauth/dist/pkce.js

@@ -3,5 +3,31 @@ export function generateCodeVerifier() {
     return crypto.randomBytes(32).toString("base64url");
 }
 export function generateCodeChallenge(verifier) {
-    return crypto.createHash("sha256").update(verifier).digest("base64url");
+    return crypto.createHash("sha256").update(validateCodeVerifier(verifier)).digest("base64url");
+}
+export function validateCodeVerifier(verifier) {
+    if (verifier.length < 43 ||
+        verifier.length > 128 ||
+        !hasOnlyPkceCharacters(verifier)) {
+        throw new Error("Poe OAuth codeVerifier must contain 43 to 128 URL-safe PKCE characters.");
+    }
+    return verifier;
+}
+export function validateCodeChallenge(challenge) {
+    if (challenge.length !== 43 || !hasOnlyPkceCharacters(challenge)) {
+        throw new Error("Poe OAuth codeChallenge must contain 43 URL-safe PKCE characters.");
+    }
+    return challenge;
+}
+function hasOnlyPkceCharacters(value) {
+    for (const character of value) {
+        const code = character.charCodeAt(0);
+        const isDigit = code >= 48 && code <= 57;
+        const isUppercase = code >= 65 && code <= 90;
+        const isLowercase = code >= 97 && code <= 122;
+        if (!isDigit && !isUppercase && !isLowercase && character !== "-" && character !== "_") {
+            return false;
+        }
+    }
+    return true;
 }