@ulexid/js 0.0.0-stage → 0.1.1

package/README.md

@@ -1,3 +1,13 @@
-# Temporary Holding Version
+# @ulexid/js
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Version `0.1.1` — [Ulexid Documentation](https://docs.ulexid.com)
+
+Browser & isomorphic OAuth 2.1 / PKCE / OIDC client SDK for [Ulexid](https://www.ulexid.com).
+
+```bash
+npm install @ulexid/js
+```
+
+## License
+
+Proprietary (`UNLICENSED`). Copyright (c) Ulexid. All rights reserved.

package/dist/index.d.ts

@@ -0,0 +1,167 @@
+/**
+ * `@ulexid/js` — Universal browser & runtime OIDC / OAuth 2.1 / Agent SDK.
+ *
+ * Uses WebCrypto (`crypto.subtle`) and standard `fetch` with zero runtime
+ * dependencies so it runs identically in browsers, Cloudflare Workers, Vercel
+ * Edge, Deno, Bun, and Node.js >= 20.
+ *
+ * Security invariants enforced by the client:
+ * - PKCE `S256` is mandatory on every authorization URL (`plain` is never emitted).
+ * - `redirect_uri` values are transmitted verbatim for exact server comparison.
+ */
+export type FetchLike = (input: string | URL | Request, init?: RequestInit) => Promise<Response>;
+export interface PkcePair {
+    readonly verifier: string;
+    readonly challenge: string;
+    readonly method: 'S256';
+}
+export interface UlexClientConfig {
+    /** Tenant or platform issuer URL, e.g. `https://ulexid.com/t/acme` or `https://auth.acme.com`. */
+    readonly issuer: string;
+    /** OAuth 2.1 `client_id` for the application. Optional for pure zero-touch agent onboarding. */
+    readonly clientId?: string;
+    /** Default exact `redirect_uri` registered on the application. */
+    readonly redirectUri?: string;
+    /** Optional custom `fetch` implementation for testing or custom runtimes. */
+    readonly fetch?: FetchLike;
+}
+export interface BuildAuthorizeUrlOptions {
+    readonly codeChallenge: string;
+    readonly state: string;
+    readonly redirectUri?: string;
+    readonly scopes?: readonly string[];
+    readonly nonce?: string;
+    /** Target workforce organization ID or slug for B2B SSO routing. */
+    readonly organization?: string;
+    /** Upstream IdP connection ID when bypassing discovery. */
+    readonly connection?: string;
+    readonly loginHint?: string;
+    readonly prompt?: 'none' | 'login' | 'consent' | 'select_account';
+}
+export interface TokenSet {
+    readonly access_token: string;
+    readonly token_type: string;
+    readonly expires_in: number;
+    readonly refresh_token?: string;
+    readonly id_token?: string;
+    readonly scope?: string;
+    readonly issued_token_type?: string;
+}
+export interface ExchangeAuthorizationCodeOptions {
+    readonly code: string;
+    readonly codeVerifier: string;
+    readonly redirectUri?: string;
+    readonly clientSecret?: string;
+}
+export interface RefreshTokensOptions {
+    readonly refreshToken: string;
+    readonly scopes?: readonly string[];
+    readonly clientSecret?: string;
+}
+export interface TokenExchangeOptions {
+    readonly subjectToken: string;
+    readonly subjectTokenType?: string;
+    readonly actorToken?: string;
+    readonly actorTokenType?: string;
+    readonly scopes?: readonly string[];
+    readonly audience?: string;
+    readonly resource?: string;
+    readonly clientSecret?: string;
+}
+export interface UserInfo {
+    readonly sub: string;
+    readonly email?: string;
+    readonly email_verified?: boolean;
+    readonly name?: string;
+    readonly given_name?: string;
+    readonly family_name?: string;
+    readonly picture?: string;
+    readonly org_id?: string;
+    readonly [claim: string]: unknown;
+}
+export interface DeviceAuthorizationResponse {
+    readonly device_code: string;
+    readonly user_code: string;
+    readonly verification_uri: string;
+    readonly verification_uri_complete: string;
+    readonly expires_in: number;
+    readonly interval: number;
+}
+export interface StartDeviceActivationOptions {
+    readonly agentName?: string;
+    readonly applicationName?: string;
+    readonly scopes?: readonly string[];
+}
+export interface AgentApprovedCredentials {
+    readonly status?: string;
+    readonly access_token?: string;
+    readonly api_key?: string;
+    readonly tenant_id?: string;
+    readonly tenant_slug?: string;
+    readonly issuer?: string;
+    readonly mcp_url?: string;
+    readonly scope?: string;
+    readonly [key: string]: unknown;
+}
+export type DevicePollResult = {
+    readonly status: 'pending';
+    readonly retryAfterSeconds: number;
+} | {
+    readonly status: 'slow_down';
+    readonly retryAfterSeconds: number;
+} | {
+    readonly status: 'expired';
+    readonly errorDescription?: string;
+} | {
+    readonly status: 'denied';
+    readonly errorDescription?: string;
+} | {
+    readonly status: 'approved';
+    readonly credentials: AgentApprovedCredentials;
+};
+export interface BuildLogoutUrlOptions {
+    readonly idTokenHint?: string;
+    readonly postLogoutRedirectUri?: string;
+    readonly state?: string;
+}
+export declare class UlexOAuthError extends Error {
+    readonly error: string;
+    readonly errorDescription?: string;
+    readonly status: number;
+    constructor(error: string, status: number, errorDescription?: string);
+}
+export declare function generateState(byteLength?: number): string;
+/**
+ * Generates an RFC 7636 PKCE `S256` verifier + challenge pair using WebCrypto.
+ */
+export declare function generatePkcePair(byteLength?: number): Promise<PkcePair>;
+export declare class UlexClient {
+    readonly issuer: string;
+    readonly clientId?: string;
+    readonly redirectUri?: string;
+    private readonly fetchImpl;
+    constructor(config: UlexClientConfig);
+    private requireClientId;
+    buildAuthorizeUrl(options: BuildAuthorizeUrlOptions): string;
+    exchangeAuthorizationCode(options: ExchangeAuthorizationCodeOptions): Promise<TokenSet>;
+    refreshTokens(options: RefreshTokensOptions): Promise<TokenSet>;
+    /**
+     * RFC 8693 OAuth 2.0 Token Exchange for scoped, short-lived agent delegation.
+     */
+    exchangeToken(options: TokenExchangeOptions): Promise<TokenSet>;
+    getUserInfo(accessToken: string): Promise<UserInfo>;
+    revokeToken(token: string, tokenTypeHint?: 'access_token' | 'refresh_token'): Promise<void>;
+    buildLogoutUrl(options?: BuildLogoutUrlOptions): string;
+    /**
+     * Starts RFC 8628 zero-touch agent onboarding (`/oauth2/device_authorization`),
+     * returning a `verification_uri_complete` deep link (`/activate?code=XXXX-YYYY`)
+     * for a human operator to approve.
+     */
+    startDeviceActivation(options?: StartDeviceActivationOptions): Promise<DeviceAuthorizationResponse>;
+    /**
+     * Polls `/api/v1/agent/poll` once for RFC 8628 device activation status.
+     */
+    pollDeviceActivation(deviceCode: string, intervalSeconds?: number): Promise<DevicePollResult>;
+    private postTokenForm;
+    private throwOAuthError;
+}

package/dist/index.js

@@ -0,0 +1,316 @@
+/**
+ * `@ulexid/js` — Universal browser & runtime OIDC / OAuth 2.1 / Agent SDK.
+ *
+ * Uses WebCrypto (`crypto.subtle`) and standard `fetch` with zero runtime
+ * dependencies so it runs identically in browsers, Cloudflare Workers, Vercel
+ * Edge, Deno, Bun, and Node.js >= 20.
+ *
+ * Security invariants enforced by the client:
+ * - PKCE `S256` is mandatory on every authorization URL (`plain` is never emitted).
+ * - `redirect_uri` values are transmitted verbatim for exact server comparison.
+ */
+export class UlexOAuthError extends Error {
+    error;
+    errorDescription;
+    status;
+    constructor(error, status, errorDescription) {
+        super(errorDescription ? `${error}: ${errorDescription}` : error);
+        this.name = 'UlexOAuthError';
+        this.error = error;
+        this.status = status;
+        this.errorDescription = errorDescription;
+    }
+}
+const BASE64_CHARS = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/';
+function bytesToBase64Url(bytes) {
+    let out = '';
+    const len = bytes.length;
+    for (let i = 0; i < len; i += 3) {
+        const b0 = bytes[i] ?? 0;
+        const b1 = i + 1 < len ? (bytes[i + 1] ?? 0) : 0;
+        const b2 = i + 2 < len ? (bytes[i + 2] ?? 0) : 0;
+        const triplet = (b0 << 16) | (b1 << 8) | b2;
+        out += BASE64_CHARS[(triplet >> 18) & 0x3f];
+        out += BASE64_CHARS[(triplet >> 12) & 0x3f];
+        out += i + 1 < len ? BASE64_CHARS[(triplet >> 6) & 0x3f] : '';
+        out += i + 2 < len ? BASE64_CHARS[triplet & 0x3f] : '';
+    }
+    return out.replace(/\+/g, '-').replace(/\//g, '_');
+}
+export function generateState(byteLength = 24) {
+    const bytes = new Uint8Array(byteLength);
+    globalThis.crypto.getRandomValues(bytes);
+    return bytesToBase64Url(bytes);
+}
+/**
+ * Generates an RFC 7636 PKCE `S256` verifier + challenge pair using WebCrypto.
+ */
+export async function generatePkcePair(byteLength = 32) {
+    if (byteLength < 32 || byteLength > 96) {
+        throw new RangeError('PKCE verifier byteLength must be between 32 and 96 bytes (RFC 7636).');
+    }
+    const randomBytes = new Uint8Array(byteLength);
+    globalThis.crypto.getRandomValues(randomBytes);
+    const verifier = bytesToBase64Url(randomBytes);
+    const encoded = new TextEncoder().encode(verifier);
+    const digest = await globalThis.crypto.subtle.digest('SHA-256', encoded);
+    const challenge = bytesToBase64Url(new Uint8Array(digest));
+    return { verifier, challenge, method: 'S256' };
+}
+function normalizeIssuer(issuer) {
+    const trimmed = issuer.trim().replace(/\/+$/, '');
+    if (!trimmed) {
+        throw new TypeError('UlexClient requires a non-empty `issuer` URL.');
+    }
+    return trimmed;
+}
+export class UlexClient {
+    issuer;
+    clientId;
+    redirectUri;
+    fetchImpl;
+    constructor(config) {
+        this.issuer = normalizeIssuer(config.issuer);
+        this.clientId = config.clientId;
+        this.redirectUri = config.redirectUri;
+        this.fetchImpl = config.fetch ?? globalThis.fetch.bind(globalThis);
+    }
+    requireClientId() {
+        if (!this.clientId) {
+            throw new UlexOAuthError('missing_client_id', 400, 'This operation requires `clientId` on UlexClientConfig.');
+        }
+        return this.clientId;
+    }
+    buildAuthorizeUrl(options) {
+        const clientId = this.requireClientId();
+        const redirectUri = options.redirectUri ?? this.redirectUri;
+        if (!redirectUri) {
+            throw new UlexOAuthError('missing_redirect_uri', 400, 'An exact `redirectUri` is required.');
+        }
+        if (!options.codeChallenge) {
+            throw new UlexOAuthError('missing_pkce_challenge', 400, 'PKCE `codeChallenge` (S256) is mandatory.');
+        }
+        if (!options.state) {
+            throw new UlexOAuthError('missing_state', 400, 'OAuth `state` parameter is required.');
+        }
+        const scopes = options.scopes?.length ? options.scopes.join(' ') : 'openid profile email';
+        const url = new URL(`${this.issuer}/oauth2/authorize`);
+        url.searchParams.set('response_type', 'code');
+        url.searchParams.set('client_id', clientId);
+        url.searchParams.set('redirect_uri', redirectUri);
+        url.searchParams.set('scope', scopes);
+        url.searchParams.set('state', options.state);
+        url.searchParams.set('code_challenge', options.codeChallenge);
+        url.searchParams.set('code_challenge_method', 'S256');
+        if (options.nonce)
+            url.searchParams.set('nonce', options.nonce);
+        if (options.organization)
+            url.searchParams.set('organization', options.organization);
+        if (options.connection)
+            url.searchParams.set('connection', options.connection);
+        if (options.loginHint)
+            url.searchParams.set('login_hint', options.loginHint);
+        if (options.prompt)
+            url.searchParams.set('prompt', options.prompt);
+        return url.toString();
+    }
+    async exchangeAuthorizationCode(options) {
+        const clientId = this.requireClientId();
+        const redirectUri = options.redirectUri ?? this.redirectUri;
+        if (!redirectUri) {
+            throw new UlexOAuthError('missing_redirect_uri', 400, 'An exact `redirectUri` is required.');
+        }
+        const body = new URLSearchParams({
+            grant_type: 'authorization_code',
+            client_id: clientId,
+            code: options.code,
+            redirect_uri: redirectUri,
+            code_verifier: options.codeVerifier,
+        });
+        if (options.clientSecret) {
+            body.set('client_secret', options.clientSecret);
+        }
+        return this.postTokenForm(body);
+    }
+    async refreshTokens(options) {
+        const clientId = this.requireClientId();
+        const body = new URLSearchParams({
+            grant_type: 'refresh_token',
+            client_id: clientId,
+            refresh_token: options.refreshToken,
+        });
+        if (options.scopes?.length) {
+            body.set('scope', options.scopes.join(' '));
+        }
+        if (options.clientSecret) {
+            body.set('client_secret', options.clientSecret);
+        }
+        return this.postTokenForm(body);
+    }
+    /**
+     * RFC 8693 OAuth 2.0 Token Exchange for scoped, short-lived agent delegation.
+     */
+    async exchangeToken(options) {
+        const clientId = this.requireClientId();
+        const body = new URLSearchParams({
+            grant_type: 'urn:ietf:params:oauth:grant-type:token-exchange',
+            client_id: clientId,
+            subject_token: options.subjectToken,
+            subject_token_type: options.subjectTokenType ?? 'urn:ietf:params:oauth:token-type:access_token',
+        });
+        if (options.actorToken) {
+            body.set('actor_token', options.actorToken);
+            body.set('actor_token_type', options.actorTokenType ?? 'urn:ietf:params:oauth:token-type:access_token');
+        }
+        if (options.scopes?.length)
+            body.set('scope', options.scopes.join(' '));
+        if (options.audience)
+            body.set('audience', options.audience);
+        if (options.resource)
+            body.set('resource', options.resource);
+        if (options.clientSecret)
+            body.set('client_secret', options.clientSecret);
+        return this.postTokenForm(body);
+    }
+    async getUserInfo(accessToken) {
+        const res = await this.fetchImpl(`${this.issuer}/oauth2/userinfo`, {
+            method: 'GET',
+            headers: {
+                authorization: `Bearer ${accessToken}`,
+                accept: 'application/json',
+            },
+        });
+        if (!res.ok) {
+            await this.throwOAuthError(res);
+        }
+        return (await res.json());
+    }
+    async revokeToken(token, tokenTypeHint) {
+        const clientId = this.requireClientId();
+        const body = new URLSearchParams({
+            client_id: clientId,
+            token,
+        });
+        if (tokenTypeHint)
+            body.set('token_type_hint', tokenTypeHint);
+        const res = await this.fetchImpl(`${this.issuer}/oauth2/revoke`, {
+            method: 'POST',
+            headers: {
+                'content-type': 'application/x-www-form-urlencoded',
+                accept: 'application/json',
+            },
+            body: body.toString(),
+        });
+        if (!res.ok) {
+            await this.throwOAuthError(res);
+        }
+    }
+    buildLogoutUrl(options = {}) {
+        const url = new URL(`${this.issuer}/oauth2/logout`);
+        if (this.clientId)
+            url.searchParams.set('client_id', this.clientId);
+        if (options.idTokenHint)
+            url.searchParams.set('id_token_hint', options.idTokenHint);
+        if (options.postLogoutRedirectUri) {
+            url.searchParams.set('post_logout_redirect_uri', options.postLogoutRedirectUri);
+        }
+        if (options.state)
+            url.searchParams.set('state', options.state);
+        return url.toString();
+    }
+    /**
+     * Starts RFC 8628 zero-touch agent onboarding (`/oauth2/device_authorization`),
+     * returning a `verification_uri_complete` deep link (`/activate?code=XXXX-YYYY`)
+     * for a human operator to approve.
+     */
+    async startDeviceActivation(options = {}) {
+        const body = new URLSearchParams();
+        if (this.clientId)
+            body.set('client_id', this.clientId);
+        if (options.agentName)
+            body.set('agent_name', options.agentName);
+        if (options.applicationName)
+            body.set('application_name', options.applicationName);
+        if (options.scopes?.length)
+            body.set('scope', options.scopes.join(' '));
+        const res = await this.fetchImpl(`${this.issuer}/oauth2/device_authorization`, {
+            method: 'POST',
+            headers: {
+                'content-type': 'application/x-www-form-urlencoded',
+                accept: 'application/json',
+            },
+            body: body.toString(),
+        });
+        if (!res.ok) {
+            await this.throwOAuthError(res);
+        }
+        return (await res.json());
+    }
+    /**
+     * Polls `/api/v1/agent/poll` once for RFC 8628 device activation status.
+     */
+    async pollDeviceActivation(deviceCode, intervalSeconds = 5) {
+        const body = new URLSearchParams({
+            grant_type: 'urn:ietf:params:oauth:grant-type:device_code',
+            device_code: deviceCode,
+        });
+        if (this.clientId)
+            body.set('client_id', this.clientId);
+        const res = await this.fetchImpl(`${this.issuer}/api/v1/agent/poll`, {
+            method: 'POST',
+            headers: {
+                'content-type': 'application/x-www-form-urlencoded',
+                accept: 'application/json',
+            },
+            body: body.toString(),
+        });
+        const payload = (await res.json().catch(() => ({})));
+        if (res.ok) {
+            return { status: 'approved', credentials: payload };
+        }
+        const code = typeof payload['error'] === 'string' ? payload['error'] : 'unknown_error';
+        const desc = typeof payload['error_description'] === 'string' ? payload['error_description'] : undefined;
+        if (code === 'authorization_pending') {
+            return { status: 'pending', retryAfterSeconds: intervalSeconds };
+        }
+        if (code === 'slow_down') {
+            return { status: 'slow_down', retryAfterSeconds: intervalSeconds + 5 };
+        }
+        if (code === 'expired_token') {
+            return { status: 'expired', errorDescription: desc };
+        }
+        if (code === 'access_denied') {
+            return { status: 'denied', errorDescription: desc };
+        }
+        throw new UlexOAuthError(code, res.status, desc);
+    }
+    async postTokenForm(body) {
+        const res = await this.fetchImpl(`${this.issuer}/oauth2/token`, {
+            method: 'POST',
+            headers: {
+                'content-type': 'application/x-www-form-urlencoded',
+                accept: 'application/json',
+            },
+            body: body.toString(),
+        });
+        if (!res.ok) {
+            await this.throwOAuthError(res);
+        }
+        return (await res.json());
+    }
+    async throwOAuthError(res) {
+        const payload = (await res.json().catch(() => ({})));
+        const errObj = payload['error'];
+        if (typeof errObj === 'string') {
+            const desc = typeof payload['error_description'] === 'string' ? payload['error_description'] : undefined;
+            throw new UlexOAuthError(errObj, res.status, desc);
+        }
+        if (typeof errObj === 'object' && errObj !== null) {
+            const nested = errObj;
+            const code = typeof nested['code'] === 'string' ? nested['code'] : `http_${res.status}`;
+            const msg = typeof nested['message'] === 'string' ? nested['message'] : undefined;
+            throw new UlexOAuthError(code, res.status, msg);
+        }
+        throw new UlexOAuthError(`http_${res.status}`, res.status, res.statusText || undefined);
+    }
+}

package/package.json

@@ -1,6 +1,26 @@
 {
   "name": "@ulexid/js",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "license": "UNLICENSED",
+  "type": "module",
+  "description": "Official browser and universal JavaScript/TypeScript OIDC, OAuth 2.1 PKCE (S256), RFC 8693 token exchange, and RFC 8628 agent device-flow SDK for Ulexid.",
+  "homepage": "https://www.ulexid.com",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ]
+}