@grest-ts/oauth 0.0.0-stage → 0.0.90

package/package.json

@@ -1,6 +1,73 @@
 {
   "name": "@grest-ts/oauth",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.0.90",
+  "type": "module",
+  "license": "MIT",
+  "description": "OAuth 2.1 authorization server (panva oidc-provider on GGHttpServer) issuing @grest-ts/auth tokens, plus a browser code+PKCE client for GGAuthSession",
+  "exports": {
+    ".": {
+      "browser": {
+        "types": "./dist/src/index-browser.d.ts",
+        "import": "./dist/src/index-browser.js"
+      },
+      "default": {
+        "types": "./dist/src/index-node.d.ts",
+        "import": "./dist/src/index-node.js"
+      }
+    },
+    "./dynamodb": {
+      "types": "./dist/src/node/store/DynamoOAuthStore.d.ts",
+      "import": "./dist/src/node/store/DynamoOAuthStore.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "scripts": {
+    "typecheck": "tsc --noEmit -p src",
+    "test": "vitest run",
+    "test:coverage": "vitest run --coverage",
+    "test:coverage:html": "vitest run --coverage --reporter=html"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/grest-ts/grest-ts.git",
+    "directory": "packages-libs/auth/oauth"
+  },
+  "homepage": "https://grest-ts.com/packages/oauth",
+  "bugs": {
+    "url": "https://github.com/grest-ts/grest-ts/issues"
+  },
+  "keywords": [
+    "typescript",
+    "framework",
+    "contract",
+    "api",
+    "microservices",
+    "testing",
+    "auth",
+    "oauth",
+    "oauth2",
+    "oidc",
+    "pkce",
+    "mcp"
+  ],
+  "engines": {
+    "node": ">=24"
+  },
+  "dependencies": {
+    "@types/oidc-provider": "9.12.1",
+    "jose": "^6.2.12",
+    "oidc-provider": "9.13.0"
+  },
+  "peerDependencies": {
+    "@grest-ts/auth": "0.0.90",
+    "@grest-ts/db-dynamodb": "0.0.90",
+    "@grest-ts/http": "0.0.90",
+    "@grest-ts/schema": "0.0.90"
+  }
+}

package/src/_dedupCheck.ts

@@ -0,0 +1,29 @@
+// =============================================================================
+// THIS FILE IS GENERATED - DO NOT EDIT
+//
+// Detects duplicate loads of @grest-ts/oauth. Two copies of a grest-ts
+// framework package in the same process break async context, validation
+// registries, and service discovery. Throw with both paths so the packaging
+// mistake is immediately diagnosable.
+//
+// Generated by scripts/packager — re-run `npm run generate` to refresh.
+// =============================================================================
+
+const __KEY = Symbol.for("grest-ts:dedup:@grest-ts/oauth");
+const __slot = globalThis as Record<symbol, unknown>;
+const __existing = __slot[__KEY] as { path: string; version: string } | undefined;
+const __here = { path: import.meta.url, version: "0.0.90" };
+// Same path + same version means the same physical package is being
+// re-evaluated by a different ESM runner (e.g. vitest projects share one
+// process but each project has its own module cache). That isn't a true
+// duplicate package — only differing paths or versions are.
+if (__existing && (__existing.path !== __here.path || __existing.version !== __here.version)) {
+    throw new Error(
+        "[@grest-ts/oauth] Duplicate package load detected.\n" +
+        "  Already loaded: " + __existing.path + " (v" + __existing.version + ")\n" +
+        "  Now loading:    " + __here.path + " (v" + __here.version + ")\n" +
+        "Two copies of grest-ts framework packages in one process break\n" +
+        "async context, validation, and service discovery. Fix the packaging."
+    );
+}
+__slot[__KEY] = __here;

package/src/browser/GGOAuthClient.test.ts

@@ -0,0 +1,76 @@
+import {afterEach, beforeEach, describe, expect, test, vi} from "vitest"
+import {GGOAuthClient} from "./GGOAuthClient"
+
+const SERVER = "https://auth.example"
+const METADATA = {
+    issuer: SERVER,
+    authorization_endpoint: `${SERVER}/oauth/authorize`,
+    token_endpoint: `${SERVER}/oauth/token`,
+    revocation_endpoint: `${SERVER}/oauth/revoke`,
+}
+
+describe("GGOAuthClient redirects", () => {
+    let assign: ReturnType<typeof vi.fn>
+    let fetchMock: ReturnType<typeof vi.fn>
+    let metadata: Record<string, string>
+
+    beforeEach(() => {
+        assign = vi.fn()
+        metadata = {...METADATA}
+        fetchMock = vi.fn(async (url: string) => {
+            if (url.endsWith("/.well-known/oauth-authorization-server")) return new Response(JSON.stringify(metadata))
+            return new Response("")
+        })
+        vi.stubGlobal("window", {location: {assign}, addEventListener: vi.fn()})
+        vi.stubGlobal("sessionStorage", {setItem: vi.fn(), getItem: vi.fn(), removeItem: vi.fn()})
+        vi.stubGlobal("fetch", fetchMock)
+    })
+    afterEach(() => vi.unstubAllGlobals())
+
+    const client = () => new GGOAuthClient({server: SERVER, clientId: "web", redirectUri: "https://app.example/cb", identity: () => ({})})
+
+    test("a failed sign-in start doesn't block the next one", async () => {
+        const oauth = client()
+        fetchMock.mockImplementationOnce(async () => new Response("down", {status: 503}))
+        await expect(oauth.authorize()).rejects.toThrow()
+        void oauth.authorize()
+        await vi.waitFor(() => expect(assign).toHaveBeenCalledTimes(1))
+        expect(new URL(assign.mock.calls[0][0]).searchParams.get("code_challenge_method")).toBe("S256")
+    })
+
+    test("a sign-in started during a logout redirect waits for it", async () => {
+        const oauth = client()
+        metadata.end_session_endpoint = `${SERVER}/oauth/logout`
+        void oauth.logout("rt")
+        void oauth.authorize()
+        await vi.waitFor(() => expect(assign).toHaveBeenCalledTimes(1))
+        expect(assign.mock.calls[0][0]).toContain("/oauth/logout")
+    })
+
+    test("a sign-in waiting behind a failed logout goes ahead", async () => {
+        const oauth = client()
+        fetchMock.mockImplementationOnce(async () => new Response("down", {status: 503}))
+        const logout = oauth.logout(undefined)
+        void oauth.authorize()
+        await expect(logout).rejects.toThrow()
+        await vi.waitFor(() => expect(assign).toHaveBeenCalledTimes(1))
+        expect(assign.mock.calls[0][0]).toContain("/oauth/authorize")
+    })
+
+    test("coming back from the back/forward cache releases the redirect", async () => {
+        const oauth = client()
+        void oauth.authorize()
+        await vi.waitFor(() => expect(assign).toHaveBeenCalledTimes(1))
+        const [event, onPageShow] = (window.addEventListener as ReturnType<typeof vi.fn>).mock.calls[0]
+        expect(event).toBe("pageshow")
+        onPageShow()
+        void oauth.authorize()
+        await vi.waitFor(() => expect(assign).toHaveBeenCalledTimes(2))
+    })
+
+    test("without an end-session endpoint, logout resolves once the token is revoked", async () => {
+        await client().logout("rt")
+        expect(fetchMock).toHaveBeenCalledWith(METADATA.revocation_endpoint, expect.objectContaining({method: "POST"}))
+        expect(assign).not.toHaveBeenCalled()
+    })
+})

package/src/browser/GGOAuthClient.ts

@@ -0,0 +1,187 @@
+/// <reference lib="dom" />
+import {decodeJwt} from "jose"
+import {NOT_AUTHORIZED} from "@grest-ts/schema"
+
+// Structurally GGAuthSession's GGAuthResult (exported only from @grest-ts/auth's browser entry).
+export interface GGOAuthResult<I> {
+    tokens: {access: {token: string, expiresAt: number}, refresh?: {token: string, expiresAt: number}}
+    data: I
+}
+
+export interface GGOAuthClientConfig<I> {
+    // Where the authorization server's metadata is (`{server}/.well-known/oauth-authorization-server`).
+    // Responses are checked against the `issuer` it declares.
+    server: string
+    clientId: string
+    redirectUri: string
+    postLogoutRedirectUri?: string
+    // RFC 8707 resource the access token is for; defaults to the issuer (an authorization server
+    // protecting its own API). Always sent: a request with `openid` and no resource would get a
+    // userinfo-only token instead of an API token.
+    resource?: string
+    scope?: string
+    // The session's identity `data`, derived from the issued access token.
+    identity: (accessToken: string) => I
+    // Assumed refresh lifetime (the token response doesn't carry it). A server-side expiry earlier
+    // than this surfaces as NOT_AUTHORIZED on refresh, which ends the session.
+    refreshTtlMs?: number
+}
+
+type Pending = {state: string, verifier: string, returnTo?: string}
+type Metadata = {issuer: string, authorization_endpoint: string, token_endpoint: string, revocation_endpoint?: string, end_session_endpoint?: string}
+
+const PENDING_KEY = "gg-oauth-pending"
+
+// Browser OAuth client (authorization code + PKCE S256), the `refresh` of a GGAuthSession — see README.
+// The token/revocation endpoints are OAuth protocol endpoints (form-encoded), not grest-ts contracts.
+export class GGOAuthClient<I = unknown> {
+
+    private metadata: Promise<Metadata> | undefined
+    // The redirect away being prepared: a second one (e.g. a signed-out view starting sign-in while
+    // logout redirects) waits for it — forever if it navigates, and takes over if it fails.
+    private leaving: Promise<void> | undefined
+
+    private readonly config: GGOAuthClientConfig<I>
+
+    constructor(config: GGOAuthClientConfig<I>) {
+        this.config = config
+    }
+
+    // Redirects the browser to the authorization server; resolves never (the page unloads).
+    public authorize = (opts?: {returnTo?: string}): Promise<void> => this.leave(async () => {
+        const meta = await this.discover()
+        const verifier = randomString()
+        const pending: Pending = {state: randomString(), verifier, returnTo: opts?.returnTo}
+        sessionStorage.setItem(PENDING_KEY, JSON.stringify(pending))
+        const url = new URL(meta.authorization_endpoint)
+        url.search = new URLSearchParams({
+            response_type: "code",
+            client_id: this.config.clientId,
+            redirect_uri: this.config.redirectUri,
+            state: pending.state,
+            code_challenge: await s256(verifier),
+            code_challenge_method: "S256",
+            resource: this.config.resource ?? meta.issuer,
+            ...(this.config.scope ? {scope: this.config.scope} : {}),
+        }).toString()
+        return url.href
+    })
+
+    public isCallback = (href: string): boolean => {
+        const url = new URL(href)
+        return url.origin + url.pathname === new URL(this.config.redirectUri).href.replace(/[?#].*$/, "")
+            && (url.searchParams.has("code") || url.searchParams.has("error"))
+    }
+
+    public handleCallback = async (href: string): Promise<{result: GGOAuthResult<I>, returnTo?: string}> => {
+        const params = new URL(href).searchParams
+        const raw = sessionStorage.getItem(PENDING_KEY)
+        sessionStorage.removeItem(PENDING_KEY)
+        const pending = raw ? JSON.parse(raw) as Pending : undefined
+        if (!pending || params.get("state") !== pending.state) throw new NOT_AUTHORIZED({debugMessage: "OAuth state mismatch"})
+        // RFC 9207: reject a response from a different authorization server (mix-up attack).
+        const iss = params.get("iss")
+        if (iss !== null && iss !== (await this.discover()).issuer) throw new NOT_AUTHORIZED({debugMessage: "OAuth issuer mismatch"})
+        const error = params.get("error")
+        if (error) throw new NOT_AUTHORIZED({debugMessage: `OAuth ${error}: ${params.get("error_description") ?? ""}`})
+        const result = await this.token({
+            grant_type: "authorization_code",
+            code: params.get("code") ?? "",
+            redirect_uri: this.config.redirectUri,
+            code_verifier: pending.verifier,
+        })
+        return {result, returnTo: pending.returnTo}
+    }
+
+    public refresh = async ({refreshToken}: {refreshToken: string}): Promise<GGOAuthResult<I>> =>
+        this.token({grant_type: "refresh_token", refresh_token: refreshToken})
+
+    // Revokes the refresh token and ends the authorization server's login session (redirects away
+    // when the server supports it).
+    public logout = (refreshToken: string | undefined): Promise<void> => this.leave(async () => {
+        const meta = await this.discover()
+        const revoke = refreshToken && meta.revocation_endpoint
+            ? fetch(meta.revocation_endpoint, {method: "POST", keepalive: true, signal: AbortSignal.timeout(5000), body: new URLSearchParams({token: refreshToken, client_id: this.config.clientId})}).then(() => undefined, () => undefined)
+            : Promise.resolve()
+        if (!meta.end_session_endpoint) {
+            await revoke
+            return undefined
+        }
+        // Revocation not awaited (keepalive outlives the navigation): the sooner the redirect, the
+        // shorter the window in which other tabs could still sign in silently.
+        const url = new URL(meta.end_session_endpoint)
+        url.search = new URLSearchParams({
+            client_id: this.config.clientId,
+            ...(this.config.postLogoutRedirectUri ? {post_logout_redirect_uri: this.config.postLogoutRedirectUri} : {}),
+        }).toString()
+        return url.href
+    })
+
+    private async leave(target: () => Promise<string | undefined>): Promise<void> {
+        while (this.leaving) await this.leaving.catch(() => undefined)
+        const run = (async () => {
+            const url = await target()
+            if (url === undefined) return
+            // Back from the back/forward cache (navigation undone): the redirect is over.
+            window.addEventListener("pageshow", () => { if (this.leaving === run) this.leaving = undefined }, {once: true})
+            window.location.assign(url)
+            await new Promise(() => undefined)
+        })()
+        this.leaving = run
+        try {
+            await run
+        } finally {
+            if (this.leaving === run) this.leaving = undefined
+        }
+    }
+
+    private async token(body: Record<string, string>): Promise<GGOAuthResult<I>> {
+        const meta = await this.discover()
+        const res = await fetch(meta.token_endpoint, {
+            method: "POST",
+            body: new URLSearchParams({...body, client_id: this.config.clientId, resource: this.config.resource ?? meta.issuer}),
+        })
+        const json = await res.json().catch(() => ({})) as Record<string, unknown>
+        if (!res.ok) {
+            // invalid_grant = the refresh/code is dead → fatal for the session; anything else may be transient.
+            if (res.status === 400 || res.status === 401) throw new NOT_AUTHORIZED({debugMessage: `OAuth ${String(json.error)}`})
+            throw new Error(`OAuth token endpoint ${res.status}`)
+        }
+        const now = Date.now()
+        const access = String(json.access_token)
+        return {
+            tokens: {
+                access: {token: access, expiresAt: now + Number(json.expires_in) * 1000},
+                ...(json.refresh_token ? {refresh: {token: String(json.refresh_token), expiresAt: now + (this.config.refreshTtlMs ?? 30 * 24 * 3600 * 1000)}} : {}),
+            },
+            data: this.config.identity(access),
+        }
+    }
+
+    private discover(): Promise<Metadata> {
+        this.metadata ??= fetch(`${this.config.server}/.well-known/oauth-authorization-server`).then(async res => {
+            if (!res.ok) throw new Error(`OAuth discovery failed: ${res.status}`)
+            return await res.json() as Metadata
+        })
+        this.metadata.catch(() => { this.metadata = undefined })
+        return this.metadata
+    }
+}
+
+// A grest-ts access token's payload, unverified — for UI identity only; the server re-verifies
+// every request.
+export function decodeAccessToken<T>(accessToken: string): {sub: string, exp: number, data: T} {
+    return decodeJwt(accessToken) as unknown as {sub: string, exp: number, data: T}
+}
+
+function randomString(): string {
+    return base64url(crypto.getRandomValues(new Uint8Array(32)))
+}
+
+async function s256(verifier: string): Promise<string> {
+    return base64url(new Uint8Array(await crypto.subtle.digest("SHA-256", new TextEncoder().encode(verifier))))
+}
+
+function base64url(bytes: Uint8Array): string {
+    return btoa(String.fromCharCode(...bytes)).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "")
+}

package/src/index-browser.ts

@@ -0,0 +1,5 @@
+import "./_dedupCheck";
+export {GGOAuthClient, decodeAccessToken} from "./browser/GGOAuthClient"
+export type {GGOAuthClientConfig, GGOAuthResult} from "./browser/GGOAuthClient"
+export {GGOAuthInteractionContract, IsGGOAuthInteraction, IsGGOAuthInteractionClient} from "./shared/interactionContract"
+export type {GGOAuthInteraction, GGOAuthInteractionClient} from "./shared/interactionContract"

package/src/index-node.ts

@@ -0,0 +1,7 @@
+import "./_dedupCheck";
+export {GGOAuthServer} from "./node/GGOAuthServer"
+export type {GGOAuthServerOptions, GGOAuthFirstPartyClient, GGOAuthResource} from "./node/GGOAuthServer"
+export type {GGOAuthStore, GGOAuthPayload} from "./node/store/GGOAuthStore"
+export {InMemoryOAuthStore} from "./node/store/InMemoryOAuthStore"
+export {GGOAuthInteractionContract, IsGGOAuthInteraction, IsGGOAuthInteractionClient} from "./shared/interactionContract"
+export type {GGOAuthInteraction, GGOAuthInteractionClient} from "./shared/interactionContract"