@keycardai/oauth 0.20.0 → 0.21.0

package/dist/esm/webApp.d.ts

@@ -0,0 +1,78 @@
+import { type OAuthAuthorizationServerMetadata } from "./discovery.js";
+import type { TokenResponse } from "./tokenExchange.js";
+export interface BeginAuthorizationOptions {
+    clientId: string;
+    /** Registered redirect URI handled by the web application. */
+    redirectUri: string;
+    /**
+     * Protected resources the authorization is targeting. Each entry is sent as
+     * its own RFC 8707 `resource` parameter, so one authorization can cover
+     * several resources and the issued token's audience covers all of them.
+     */
+    resources?: readonly string[];
+    scopes?: readonly string[];
+    /** Pre-discovered metadata. When set, no discovery request is made. */
+    metadata?: OAuthAuthorizationServerMetadata;
+    signal?: AbortSignal;
+}
+export interface AuthorizationRedirect {
+    /** The authorization URL to redirect the user's browser to. */
+    url: string;
+    /** Generated CSRF value to store until the callback. */
+    state: string;
+    /** Generated PKCE verifier to store until the callback; never send it to the browser. */
+    codeVerifier: string;
+    /**
+     * The resources the authorization request was scoped to. They are not needed
+     * to redeem the code — the authorization server derives the issued token's
+     * audience from the code itself — but applications commonly need to know
+     * which resources a session was authorized for.
+     */
+    resources: string[];
+}
+export interface CompleteAuthorizationOptions {
+    /** Query parameters the callback route received. */
+    callbackParams: URLSearchParams | Record<string, string>;
+    /** The `state` stored at the begin step. */
+    state: string;
+    /** The `codeVerifier` stored at the begin step. */
+    codeVerifier: string;
+    clientId: string;
+    /** The same registered redirect URI used at the begin step. */
+    redirectUri: string;
+    /** Client secret for confidential clients. Public clients omit it. */
+    clientSecret?: string;
+    /** Pre-discovered metadata. When set, no discovery request is made. */
+    metadata?: OAuthAuthorizationServerMetadata;
+    signal?: AbortSignal;
+}
+/**
+ * Begin a web-app authorization-code-with-PKCE flow.
+ *
+ * For applications that own a registered redirect URI and receive the callback
+ * on their own route, where the loopback listener `authenticate()` runs is
+ * wrong. Generates the PKCE pair and a CSRF `state`, resolves the
+ * `authorization_endpoint` by discovery, and builds the authorization URL with
+ * one `resource` parameter per entry of `resources`.
+ *
+ * The SDK holds no state between begin and complete: where `state` and
+ * `codeVerifier` live between the redirect and the callback (a session, a
+ * signed cookie) is the application's concern, which is what makes the flow
+ * safe under concurrent sign-ins and multi-process servers.
+ */
+export declare function beginAuthorization(issuer: string, options: BeginAuthorizationOptions): Promise<AuthorizationRedirect>;
+/**
+ * Complete a web-app authorization-code-with-PKCE flow from the callback route.
+ *
+ * Callback validation happens before discovery or any token request: a
+ * callback carrying `error` throws `AuthorizationDeniedError`, a missing or
+ * non-matching `state` throws `StateMismatchError`, and a missing `code`
+ * throws `OAuthError("invalid_request")`.
+ *
+ * No RFC 8707 `resource` parameter is sent on the token request: the
+ * authorization server derives the issued token's audience from the
+ * authorization code, which already records the resources authorized at the
+ * begin step.
+ */
+export declare function completeAuthorization(issuer: string, options: CompleteAuthorizationOptions): Promise<TokenResponse>;
+//# sourceMappingURL=webApp.d.ts.map

package/dist/esm/webApp.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"webApp.d.ts","sourceRoot":"","sources":["../../src/webApp.ts"],"names":[],"mappings":"AACA,OAAO,EAAoC,KAAK,gCAAgC,EAAE,MAAM,gBAAgB,CAAC;AAGzG,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAMxD,MAAM,WAAW,yBAAyB;IACxC,QAAQ,EAAE,MAAM,CAAC;IACjB,8DAA8D;IAC9D,WAAW,EAAE,MAAM,CAAC;IACpB;;;;OAIG;IACH,SAAS,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC9B,MAAM,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC3B,uEAAuE;IACvE,QAAQ,CAAC,EAAE,gCAAgC,CAAC;IAC5C,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAED,MAAM,WAAW,qBAAqB;IACpC,+DAA+D;IAC/D,GAAG,EAAE,MAAM,CAAC;IACZ,wDAAwD;IACxD,KAAK,EAAE,MAAM,CAAC;IACd,yFAAyF;IACzF,YAAY,EAAE,MAAM,CAAC;IACrB;;;;;OAKG;IACH,SAAS,EAAE,MAAM,EAAE,CAAC;CACrB;AAED,MAAM,WAAW,4BAA4B;IAC3C,oDAAoD;IACpD,cAAc,EAAE,eAAe,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACzD,4CAA4C;IAC5C,KAAK,EAAE,MAAM,CAAC;IACd,mDAAmD;IACnD,YAAY,EAAE,MAAM,CAAC;IACrB,QAAQ,EAAE,MAAM,CAAC;IACjB,+DAA+D;IAC/D,WAAW,EAAE,MAAM,CAAC;IACpB,sEAAsE;IACtE,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,uEAAuE;IACvE,QAAQ,CAAC,EAAE,gCAAgC,CAAC;IAC5C,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAsB,kBAAkB,CACtC,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,yBAAyB,GACjC,OAAO,CAAC,qBAAqB,CAAC,CA0BhC;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,qBAAqB,CACzC,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,4BAA4B,GACpC,OAAO,CAAC,aAAa,CAAC,CAmCxB"}

package/dist/esm/webApp.js

@@ -0,0 +1,88 @@
+import base64url from "./base64url.js";
+import { fetchAuthorizationServerMetadata } from "./discovery.js";
+import { AuthorizationDeniedError, OAuthError, StateMismatchError } from "./errors.js";
+import { buildAuthorizeUrl, exchangeAuthorizationCode, generatePkcePair } from "./pkce.js";
+/**
+ * Begin a web-app authorization-code-with-PKCE flow.
+ *
+ * For applications that own a registered redirect URI and receive the callback
+ * on their own route, where the loopback listener `authenticate()` runs is
+ * wrong. Generates the PKCE pair and a CSRF `state`, resolves the
+ * `authorization_endpoint` by discovery, and builds the authorization URL with
+ * one `resource` parameter per entry of `resources`.
+ *
+ * The SDK holds no state between begin and complete: where `state` and
+ * `codeVerifier` live between the redirect and the callback (a session, a
+ * signed cookie) is the application's concern, which is what makes the flow
+ * safe under concurrent sign-ins and multi-process servers.
+ */
+export async function beginAuthorization(issuer, options) {
+    const metadata = options.metadata
+        ?? await fetchAuthorizationServerMetadata(issuer, { signal: options.signal });
+    if (!metadata.authorization_endpoint) {
+        throw new Error(`Authorization server "${issuer}" does not advertise an authorization_endpoint`);
+    }
+    const { codeVerifier, codeChallenge } = await generatePkcePair("S256");
+    const stateBytes = new Uint8Array(32);
+    crypto.getRandomValues(stateBytes);
+    const state = base64url.encode(stateBytes.buffer);
+    const resources = [...options.resources ?? []];
+    const url = buildAuthorizeUrl(metadata.authorization_endpoint, {
+        clientId: options.clientId,
+        redirectUri: options.redirectUri,
+        codeChallenge,
+        state,
+        scope: options.scopes && options.scopes.length > 0 ? options.scopes.join(" ") : undefined,
+        resources,
+    });
+    return { url, state, codeVerifier, resources };
+}
+/**
+ * Complete a web-app authorization-code-with-PKCE flow from the callback route.
+ *
+ * Callback validation happens before discovery or any token request: a
+ * callback carrying `error` throws `AuthorizationDeniedError`, a missing or
+ * non-matching `state` throws `StateMismatchError`, and a missing `code`
+ * throws `OAuthError("invalid_request")`.
+ *
+ * No RFC 8707 `resource` parameter is sent on the token request: the
+ * authorization server derives the issued token's audience from the
+ * authorization code, which already records the resources authorized at the
+ * begin step.
+ */
+export async function completeAuthorization(issuer, options) {
+    const params = options.callbackParams instanceof URLSearchParams
+        ? options.callbackParams
+        : new URLSearchParams(options.callbackParams);
+    const error = params.get("error");
+    if (error) {
+        throw new AuthorizationDeniedError(error, params.get("error_description") ?? undefined, params.get("error_uri") ?? undefined);
+    }
+    const callbackState = params.get("state");
+    if (callbackState === null || !timingSafeEqual(callbackState, options.state)) {
+        throw new StateMismatchError();
+    }
+    const code = params.get("code");
+    if (!code) {
+        throw new OAuthError("invalid_request", "Authorization callback is missing 'code'");
+    }
+    return exchangeAuthorizationCode(issuer, code, {
+        codeVerifier: options.codeVerifier,
+        redirectUri: options.redirectUri,
+        clientId: options.clientId,
+        clientSecret: options.clientSecret,
+        metadata: options.metadata,
+        signal: options.signal,
+    });
+}
+/** Compare two strings without leaking their common prefix length via timing. */
+function timingSafeEqual(a, b) {
+    const left = new TextEncoder().encode(a);
+    const right = new TextEncoder().encode(b);
+    let diff = left.length ^ right.length;
+    for (let i = 0; i < left.length; i++) {
+        diff |= left[i] ^ right[i % (right.length || 1)];
+    }
+    return diff === 0;
+}
+//# sourceMappingURL=webApp.js.map

package/dist/esm/webApp.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"webApp.js","sourceRoot":"","sources":["../../src/webApp.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@keycardai/oauth",
-  "version": "0.20.0",
+  "version": "0.21.0",
   "description": "[Preview] OAuth 2.0 primitives for Keycard: JWKS keyring, JWT signing/verification, server-tier token verifier, AccessContext, ClientSecret credentials, and impersonation via RFC 8693 token exchange",
   "license": "MIT",
   "repository": {
@@ -94,6 +94,16 @@
       "import": "./dist/esm/pkce.js",
       "require": "./dist/cjs/pkce.js",
       "types": "./dist/esm/pkce.d.ts"
+    },
+    "./webApp": {
+      "import": "./dist/esm/webApp.js",
+      "require": "./dist/cjs/webApp.js",
+      "types": "./dist/esm/webApp.d.ts"
+    },
+    "./userinfo": {
+      "import": "./dist/esm/userinfo.js",
+      "require": "./dist/cjs/userinfo.js",
+      "types": "./dist/esm/userinfo.d.ts"
     }
   },
   "files": [