@wtfalch/auth 0.11.0 → 0.12.0

package/README.md

@@ -99,6 +99,83 @@ again. `forget()` sets the same mark, so a sign-out does not undo itself.
 `completeSignIn()` at the callback returns `signed-in`, `silent-refused` — the
 answer to a silent attempt, not a failure — or `error`.
 
+### Hub seams: a non-default opener, storage, refresh and scopes
+
+Four options on `BrowserAuthOptions` exist for a client that is not a
+plain same-origin web page — a phone driving a system browser, a desktop app,
+or a hub app juggling more than one issuer session. Every default matches the
+behaviour above exactly, so a caller that sets none of them sees no change.
+
+```ts
+const auth = createBrowserAuth({
+  issuer: 'https://auth.wtfalch.dev',
+  clientId: '…',
+  open: (url) => Browser.open({ url }),   // Capacitor's system-browser opener
+  store: capacitorSecureStore,            // see "Storage stays synchronous" below
+  extraScopes: ['urn:zitadel:iam:org:project:id:<mail project>:aud'],
+});
+```
+
+- **`open(url)`** replaces `window.location.assign` — what leaves the tab for
+  the issuer. It may return a promise, which is awaited before `authorize()`
+  returns; the default stays synchronous.
+- **`store`** replaces the `sessionStorage` wrapper that holds the token,
+  verifier, return path and silent-tried mark, with a plain
+  `{ get, set, drop }` shape — `get` synchronous, `set`/`drop` allowed to
+  return a promise (see "Storage: `get` stays synchronous" below). Two
+  `createBrowserAuth` instances given different stores never see each other's
+  values — one hub's session cannot leak into another's held in the same tab.
+- **`refresh()`**, a new method on the returned client, posts the
+  `refresh_token` grant and stores the session it gets back — awaiting the
+  store's write before it resolves, so an app that awaits `refresh()` knows
+  the rotated token is durable, not just in memory. ZITADEL rotates the
+  refresh token on every use — the one just spent cannot be reused — so a
+  refusal (`{ kind: 'refused' }`) drops the held session rather than leaving a
+  dead one behind; `{ kind: 'no-refresh-token' }` means there was nothing to
+  refresh. Concurrent calls share one in-flight exchange: two callers racing
+  near expiry both get the freshly rotated session, rather than the second
+  spending the first's now-dead token and refusing a session the first just
+  set. The refresh token itself never appears on the value `currentSession()`
+  or `refresh()` returns to app code — only `refresh()`'s own closure over
+  the store can reach it — because a value passed around the app should not
+  double as something that can mint new access tokens.
+- **`extraScopes`** appends to `scope` (or its default) at `/authorize`. Each
+  entry is itself split on whitespace and de-duplicated against the rest —
+  `['read write']` and `['read', 'write']` do the same thing — so an audience
+  scope for one project, say, never lands twice or leaves a stray space when
+  an entry is empty. The refresh grant freezes the audience from first
+  sign-in, so this only matters there.
+- **`forget()`** is now `Promise<void>` rather than `void`, the one signature
+  change here: it awaits the store's writes, the same as `completeSignIn()`
+  and `refresh()`.
+
+**Storage: `get` stays synchronous; `set` and `drop` may be async.**
+`currentSession()` and `silentSignInAvailable()` are synchronous methods on
+every `createBrowserAuth` client, defaults included, and both read only
+through the store's `get` — so `get` cannot become a promise without changing
+that contract for every existing caller, not just a Capacitor one. `set` and
+`drop` can, because the methods that write through them —
+`completeSignIn()`, `refresh()` and `forget()` — are already async: each now
+awaits the store's write before it returns, so a write is durable by the time
+an app that awaits one of those methods acts on it.
+
+A Capacitor secure-storage store bridges the two: keep a synchronous
+in-memory mirror for `get` to read, and have `set`/`drop` write the mirror
+*and* await the secure store, so the promise those methods return resolves
+only once the write actually lands. Hydrate the mirror from the secure store
+once at startup, before the app's first call to `currentSession()` — a `get`
+before that has nothing to read and reports no session even when one is
+held.
+
+**Namespace clients (`namespace: {...}`) do not take a custom `store`.** That
+path already coordinates a session across tabs and clients through its own
+fixed `sessionStorage`/`localStorage` keys (see `namespace-browser.ts`), and
+swapping in an injected store would mean redesigning that coordination, not
+wiring one in — `createBrowserAuth` throws rather than silently ignoring it.
+`open` and `extraScopes` do apply there, unchanged. `refresh()` is present but
+always reports `no-refresh-token`: the namespace exchange never retains a
+refresh token to begin with.
+
 ## Configuration
 
 | | |
@@ -139,6 +216,18 @@ app URL, and refreshes itself when the id token is close to expiring.
 `ORG_CLAIM` is enforced on every token: a token from another organisation is
 refused even when the issuer and the signature are good.
 
+The cookie never carries an access token -- every exchange and refresh
+discards it. `accessToken(cookieValue)` reads one back for a server that
+needs to call a resource server on a signed-in person's behalf: it runs the
+refresh grant itself and returns `{ ok: true, accessToken, expiresAt,
+cookies }` or `{ ok: false, reason }`. The refresh token is spent on every
+call, so `cookies` -- always the re-sealed session, carrying the grant's
+fresh id token even when the refresh token itself did not rotate -- must be
+persisted before the session is read or `accessToken` called again.
+Not available in namespace mode. `extraScopes` on `createAuth`'s options
+adds to the scope every sign-in and QR device grant asks for, for a
+resource server's own audience scope. See `docs/adopting.md` for both.
+
 ## Passkeys and QR sign-in
 
 Passkeys live on each app's own domain: the relying-party ID is the app's

package/dist/auth.d.ts

@@ -163,6 +163,33 @@ export interface QrPollResult {
     reason?: string;
     cookies: SetCookie[];
 }
+/**
+ * Why `accessToken` refused: no session cookie, or one that will not open
+ * (`no_session`); a session with no refresh token (`no_refresh_token`); or
+ * the issuer refusing the refresh grant itself, including the same
+ * organisation/id-token validation `readCookie`'s refresh path applies
+ * (`refused`). A transient outage is not in this list -- `accessToken`
+ * throws for that instead, see its own doc comment.
+ */
+export type AccessTokenReason = 'no_session' | 'no_refresh_token' | 'refused';
+export type AccessTokenResult = {
+    ok: true;
+    /** The issuer's own bearer token. Never the id token, and never what was in the cookie. */
+    accessToken: string;
+    /** Epoch milliseconds. */
+    expiresAt: number;
+    /**
+     * The re-sealed session -- always exactly one cookie, even when the
+     * refresh token itself did not rotate, because the grant always
+     * returns a fresh id token too. Persist it, e.g. as a `Set-Cookie`,
+     * before the value passed in is used again: the refresh token in it
+     * is spent.
+     */
+    cookies: SetCookie[];
+} | {
+    ok: false;
+    reason: AccessTokenReason;
+};
 export interface Auth {
     readonly sessionCookieName: string;
     /** GET {basePath}/start?next=&intent= : begins the OIDC flow; the issuer sends the browser to {basePath}/login?authRequest= */
@@ -387,6 +414,36 @@ export interface Auth {
      * failed callback rather than throwing.
      */
     pollQrSignIn(request: Request): Promise<QrPollResult>;
+    /**
+     * Trades a sealed session cookie's value (`readCookie`'s own `value`
+     * parameter, not a `Cookie` header) for a fresh issuer access token. The
+     * cookie never holds one -- `Tokens` keeps only an id token and a refresh
+     * token -- so this runs the refresh grant itself and reads `access_token`
+     * straight off that response, applying the same id-token and organisation
+     * checks `readCookie`'s own refresh path applies, through the same
+     * `Oidc.refresh`.
+     *
+     * The refresh token is SPENT on every call: the issuer rotates it on each
+     * grant. A caller must serialise calls for one session -- two in flight
+     * would race the same token -- and persist `cookies`, the re-sealed
+     * session this always returns on `ok: true` (a fresh id token comes back
+     * on every grant, even on the rare one that does not rotate the refresh
+     * token), before the session is read or `accessToken` is called again.
+     *
+     * `ok: false` is a definitive refusal -- no session, no refresh token in
+     * it, or the issuer refusing the grant (`isOAuthRefusal`, or the same
+     * organisation/id-token check `readCookie` applies). A transient issuer
+     * outage (network error, 5xx, 429) throws instead of answering
+     * `ok: false`: unlike `readCookie`, there is no still-valid access token
+     * to fall back to, because one was never kept.
+     *
+     * Not available in namespace mode: those sessions are a handle to a
+     * server-held record, refreshed under a lease (see `namespace-session.ts`)
+     * that serialises rotation across replicas. Spending the refresh token
+     * here would run outside that lease and could race, or duplicate, the
+     * rotation the lease exists to prevent. Throws when `namespace` is set.
+     */
+    accessToken(cookieValue: string): Promise<AccessTokenResult>;
 }
 export declare function createAuth(input: AuthOptions): Auth;
 export type { AuthRequest, NewUser, SetCookie };

package/dist/auth.js

@@ -175,11 +175,21 @@ export function createAuth(input) {
     /**
      * Where a sign-out lands: the issuer's own logout, so its session ends and
      * the next sign-in asks who again, rather than straight back to
-     * `afterLogout`. What this function can see fail -- no id token to hint
-     * with, no `end_session_endpoint` published, the issuer not answering --
-     * falls back to the plain redirect a sign-out has always ended with.
-     * Losing the issuer's co-operation is never a reason to fail somebody's
-     * sign-out.
+     * `afterLogout`. What this function can see fail -- no `end_session_endpoint`
+     * published, the issuer not answering -- falls back to the plain redirect a
+     * sign-out has always ended with. Losing the issuer's co-operation is never
+     * a reason to fail somebody's sign-out.
+     *
+     * Having no id token is the one failure that does not fall back, because the
+     * plain redirect leaves the issuer's session standing and the next sign-in is
+     * silent. `end_session` cannot rescue it either: without a hint the issuer
+     * takes its v1 branch and ends v1 user-agent sessions, of which a v2 sign-in
+     * has none. Routing a hint-less `end_session` to the hosted login instead
+     * needs the instance's `loginV2.required`, which overrides every app's own
+     * `loginVersion.loginV2.baseUri` with the instance's -- and each app here
+     * hosts its own sign-in at `/auth`, so that flag is not available to us.
+     * The hosted login's `/logout` sits at the issuer's origin, where
+     * `scripts/provision.mjs` points the instance's `loginV2.baseUri`.
      *
      * `afterLogout` not being a registered `post_logout_redirect_uri` is a
      * failure this function cannot see: that request reaches the issuer, which
@@ -191,11 +201,12 @@ export function createAuth(input) {
      */
     const endIssuerSession = async (idToken, cookies) => {
         const afterLogout = new URL(options().afterLogout, options().appUrl).href;
-        const target = idToken
-            ? await oidc()
-                .endSessionUrl(idToken, afterLogout)
-                .catch(() => null)
-            : null;
+        if (!idToken) {
+            return redirect(new URL('/logout', options().issuer).href, cookies, 303);
+        }
+        const target = await oidc()
+            .endSessionUrl(idToken, afterLogout)
+            .catch(() => null);
         return redirect(target?.href ?? afterLogout, cookies, 303);
     };
     const logout = async (request) => {
@@ -644,7 +655,7 @@ export function createAuth(input) {
     const startQrSignIn = async () => {
         if (options().namespace && !(await sessions.bindingActive()))
             throw new AuthError('unavailable', 'the namespace binding is not active');
-        const device = await requestDeviceAuthorization(options(), scopeFor(options().organizationId));
+        const device = await requestDeviceAuthorization(options(), scopeFor(options().organizationId, options().extraScopes));
         const cookie = await sealQrTransaction(options(), { dc: device.deviceCode, iv: device.interval }, device.expiresIn);
         return {
             url: qrVerificationUrl(options(), device.verificationUriComplete),
@@ -695,6 +706,42 @@ export function createAuth(input) {
         await replacePreviousSession(request.headers.get('cookie'));
         return { status: 'signed_in', cookies: [cleared, session] };
     };
+    const accessToken = async (cookieValue) => {
+        if (options().namespace) {
+            throw new Error('@wtfalch/auth: accessToken is not supported in namespace mode -- those sessions refresh under a server-side lease this would bypass');
+        }
+        const session = await openSession(options(), cookieValue);
+        if (!session)
+            return { ok: false, reason: 'no_session' };
+        if (!session.rt)
+            return { ok: false, reason: 'no_refresh_token' };
+        let tokens;
+        try {
+            tokens = await oidc().refresh(session.rt);
+        }
+        catch (error) {
+            if (error instanceof AuthError || isOAuthRefusal(error))
+                return { ok: false, reason: 'refused' };
+            throw error;
+        }
+        if (!tokens.accessToken || tokens.accessTokenExpiresAt === undefined) {
+            // The issuer answered the grant but sent no access token -- treat it
+            // the same as a refusal rather than handing back an unusable result.
+            return { ok: false, reason: 'refused' };
+        }
+        // Always re-sealed, even when the refresh token itself did not rotate:
+        // the grant always returns a fresh id token, and readCookie's own
+        // refresh path re-seals on every successful refresh for the same reason.
+        const cookies = [
+            await sealSession(options(), { idt: tokens.idToken, rt: tokens.refreshToken }),
+        ];
+        return {
+            ok: true,
+            accessToken: tokens.accessToken,
+            expiresAt: tokens.accessTokenExpiresAt,
+            cookies,
+        };
+    };
     const failure = (reason, cookies) => {
         const url = new URL(options().onError, options().appUrl);
         url.searchParams.set('auth_error', reason);
@@ -748,6 +795,7 @@ export function createAuth(input) {
         finishPasskeySignIn,
         startQrSignIn,
         pollQrSignIn,
+        accessToken,
     };
 }
 function redirect(location, cookies, status = 302) {

package/dist/browser.d.ts

@@ -37,6 +37,23 @@ import type { NamespaceSelection } from './namespaces.js';
  * the tab spins. `forget()` sets the same mark, so pressing sign out does not
  * bounce somebody straight back in — a sign-out that undoes itself is not one.
  */
+/** Leaves the tab for the issuer instead of `window.location.assign`. A
+ *  phone driving a system browser (Capacitor, say) supplies its own; may
+ *  return a promise, which is awaited before `authorize()` returns. */
+export type BrowserOpener = (url: string) => void | Promise<void>;
+/**
+ * Where the token, verifier, return path and silent-tried mark live.
+ * `get` is synchronous: `currentSession()` and `silentSignInAvailable()` are
+ * synchronous on `BrowserAuth`, defaults included, and read only through it.
+ * `set` and `drop` may return a promise — for a store backed by something
+ * like Capacitor secure storage — which `completeSignIn`, `refresh` and
+ * `forget` await before they return. See the package README.
+ */
+export interface BrowserAuthStore {
+    get(key: string): string | null;
+    set(key: string, value: string): void | Promise<void>;
+    drop(key: string): void | Promise<void>;
+}
 export interface BrowserAuthOptions {
     /** Public namespace registry projection; never include broker or cookie secrets. */
     namespace?: NamespaceSelection;
@@ -57,6 +74,20 @@ export interface BrowserAuthOptions {
     callbackPath?: string;
     /** Scopes to ask for. `openid` is required; the rest is the app's business. */
     scope?: string;
+    /**
+     * Extra scopes appended to `scope` at `/authorize`, de-duplicated with it —
+     * an audience scope for one project, say. The refresh grant freezes the
+     * audience from first sign-in, so this has no effect on `refresh()`.
+     */
+    extraScopes?: string[];
+    /** Leaves the tab for the issuer. Default: `window.location.assign`. */
+    open?: BrowserOpener;
+    /**
+     * Holds the token, verifier, return path and silent-tried mark. Default
+     * wraps `sessionStorage` and never throws. Two instances given different
+     * stores never see each other's values — inject one per hub.
+     */
+    store?: BrowserAuthStore;
 }
 export interface BrowserSession {
     namespaceId?: string;
@@ -82,6 +113,25 @@ export type SignInOutcome = {
     kind: 'error';
     error: string;
 };
+/** What `refresh()` found. */
+export type RefreshOutcome = {
+    kind: 'refreshed';
+    session: BrowserSession;
+}
+/** No session held, or the held one has no refresh token. Not an error. */
+ | {
+    kind: 'no-refresh-token';
+}
+/**
+ * The issuer would not rotate the refresh token. ZITADEL spends a refresh
+ * token on every use whether it accepts or refuses it, so either way the
+ * old one cannot be tried again — the held session is dropped before this
+ * returns.
+ */
+ | {
+    kind: 'refused';
+    error: string;
+};
 export interface BrowserAuth {
     /** Another account/binding replaced this context; require a deliberate sign-in. */
     accountChanged(): boolean;
@@ -112,7 +162,18 @@ export interface BrowserAuth {
     signIn(returnTo?: string): Promise<void>;
     /** Finish the flow at the callback path. */
     completeSignIn(search?: string): Promise<SignInOutcome>;
-    /** Drop the session, and do not silently take another in this tab. */
-    forget(): void;
+    /**
+     * Rotate the held refresh token for a new session, when one is held.
+     * `currentSession()` never carries the refresh token itself — a value
+     * passed around the app should not be able to mint new access tokens — so
+     * this is the only way to use it. A refusal drops the held session.
+     * Concurrent calls share one in-flight exchange, so two callers racing
+     * near expiry both get the freshly rotated session rather than one losing
+     * to the other's now-spent refresh token.
+     */
+    refresh(): Promise<RefreshOutcome>;
+    /** Drop the session, and do not silently take another in this tab. Awaits
+     *  the store's writes, so a caller that awaits this knows they landed. */
+    forget(): Promise<void>;
 }
 export declare function createBrowserAuth(options: BrowserAuthOptions): BrowserAuth;

package/dist/browser.js

@@ -6,7 +6,7 @@ const RETURN = 'wtfalch.auth.return';
 const TRIED = 'wtfalch.auth.silent-tried';
 /** Storage that never throws. A browser refusing it signs in every visit,
  *  which is worse than the alternative but not broken. */
-const store = {
+const defaultStore = {
     get(key) {
         try {
             return sessionStorage.getItem(key);
@@ -47,17 +47,33 @@ function verifier() {
     // inside the 43..128 the spec allows.
     return base64url(crypto.getRandomValues(new Uint8Array(32)).buffer);
 }
+function publicSession(session) {
+    const { refreshToken, ...rest } = session;
+    return rest;
+}
 export function createBrowserAuth(options) {
-    if (options.namespace)
+    if (options.namespace) {
+        // The namespace path coordinates a shared session across tabs and
+        // clients through fixed `sessionStorage`/`localStorage` keys (see
+        // `namespace-browser.ts`); swapping that for an injected store means
+        // redesigning that coordination, not wiring one in. Refused with a clear
+        // error rather than silently ignored.
+        if (options.store)
+            throw new Error('createBrowserAuth: a namespace client does not support a custom store');
         return createNamespaceBrowserAuth(options, options.namespace);
+    }
     const origin = options.origin ?? window.location.origin;
     const callbackPath = options.callbackPath ?? '/auth/callback';
-    const scope = options.scope ?? 'openid email profile offline_access';
+    const baseScope = options.scope ?? 'openid email profile offline_access';
+    const extraScopes = (options.extraScopes ?? []).flatMap((s) => s.split(/\s+/).filter(Boolean));
+    const scope = Array.from(new Set([...baseScope.split(/\s+/).filter(Boolean), ...extraScopes])).join(' ');
     const redirectUri = `${origin}${callbackPath}`;
+    const store = options.store ?? defaultStore;
+    const open = options.open ?? ((url) => window.location.assign(url));
     const authorize = async (prompt, returnTo) => {
         const proof = verifier();
-        store.set(VERIFIER, proof);
-        store.set(RETURN, returnTo);
+        await store.set(VERIFIER, proof);
+        await store.set(RETURN, returnTo);
         const url = new URL(`${options.issuer}/oauth/v2/authorize`);
         url.searchParams.set('client_id', options.clientId);
         url.searchParams.set('redirect_uri', redirectUri);
@@ -67,21 +83,68 @@ export function createBrowserAuth(options) {
         url.searchParams.set('code_challenge_method', 'S256');
         if (prompt)
             url.searchParams.set('prompt', prompt);
-        window.location.assign(url.toString());
+        await open(url.toString());
     };
-    const currentSession = () => {
+    const readStored = () => {
         const raw = store.get(TOKEN);
         if (!raw)
             return null;
         try {
-            const session = JSON.parse(raw);
-            return session.expiresAt - 60_000 > Date.now() ? session : null;
+            return JSON.parse(raw);
         }
         catch {
             return null;
         }
     };
+    const currentSession = () => {
+        const session = readStored();
+        if (!session)
+            return null;
+        return session.expiresAt - 60_000 > Date.now() ? publicSession(session) : null;
+    };
     const silentSignInAvailable = () => !currentSession() && !store.get(TRIED);
+    // Shared by every `refresh()` call on this instance, so two callers racing
+    // near expiry share one exchange rather than each spending the same
+    // refresh token — ZITADEL rotates it on first use, so the second would be
+    // refused and drop the session the first just set.
+    let refreshing;
+    const performRefresh = async () => {
+        const session = readStored();
+        if (!session?.refreshToken)
+            return { kind: 'no-refresh-token' };
+        const response = await fetch(`${options.issuer}/oauth/v2/token`, {
+            method: 'POST',
+            headers: { 'content-type': 'application/x-www-form-urlencoded' },
+            body: new URLSearchParams({
+                grant_type: 'refresh_token',
+                client_id: options.clientId,
+                refresh_token: session.refreshToken,
+            }),
+        });
+        if (!response.ok) {
+            // ZITADEL spends the refresh token on every use, whether it accepts
+            // or refuses it: either way the old one cannot be tried again, so
+            // the held session goes with it.
+            await store.drop(TOKEN);
+            const body = await response.text();
+            return {
+                kind: 'refused',
+                error: `the issuer refused the refresh (${response.status}): ${body.slice(0, 200)}`,
+            };
+        }
+        const token = (await response.json());
+        if (!token.access_token || !token.refresh_token) {
+            await store.drop(TOKEN);
+            return { kind: 'refused', error: 'the issuer returned an incomplete refresh response' };
+        }
+        const next = {
+            accessToken: token.access_token,
+            expiresAt: Date.now() + (token.expires_in ?? 3600) * 1000,
+            refreshToken: token.refresh_token,
+        };
+        await store.set(TOKEN, JSON.stringify(next));
+        return { kind: 'refreshed', session: publicSession(next) };
+    };
     return {
         accountChanged: () => false,
         currentSession,
@@ -89,14 +152,14 @@ export function createBrowserAuth(options) {
         async trySilentSignIn(returnTo = window.location.pathname) {
             if (!silentSignInAvailable())
                 return false;
-            store.set(TRIED, '1');
+            await store.set(TRIED, '1');
             await authorize('none', returnTo);
             return true;
         },
         async signIn(returnTo = window.location.pathname) {
             // A deliberate sign-in clears the mark: whatever the issuer said before,
             // the person is asking now.
-            store.drop(TRIED);
+            await store.drop(TRIED);
             await authorize(undefined, returnTo);
         },
         async completeSignIn(search = window.location.search) {
@@ -106,8 +169,8 @@ export function createBrowserAuth(options) {
             // Removed whatever happens: a code that failed to exchange must not be
             // retried against the same proof, and a stale verifier is what makes the
             // *next* sign-in fail confusingly.
-            store.drop(VERIFIER);
-            store.drop(RETURN);
+            await store.drop(VERIFIER);
+            await store.drop(RETURN);
             const issuerError = params.get('error');
             if (issuerError) {
                 // The three the spec gives for "I would have had to ask them
@@ -151,18 +214,29 @@ export function createBrowserAuth(options) {
             const session = {
                 accessToken: token.access_token,
                 expiresAt: Date.now() + (token.expires_in ?? 3600) * 1000,
+                refreshToken: token.refresh_token,
             };
-            store.set(TOKEN, JSON.stringify(session));
+            await store.set(TOKEN, JSON.stringify(session));
             // Signed in: a later silent attempt in this tab is allowed again, which
             // matters when the token expires and the page reloads.
-            store.drop(TRIED);
-            return { kind: 'signed-in', session, returnTo };
+            await store.drop(TRIED);
+            return { kind: 'signed-in', session: publicSession(session), returnTo };
+        },
+        async refresh() {
+            // One in-flight exchange per instance: two callers racing near expiry
+            // must not both spend the same refresh token — ZITADEL rotates it on
+            // first use, so the second would be refused and drop the session the
+            // first just set.
+            refreshing ??= performRefresh().finally(() => {
+                refreshing = undefined;
+            });
+            return refreshing;
         },
-        forget() {
-            store.drop(TOKEN);
+        async forget() {
+            await store.drop(TOKEN);
             // The mark stays set: a sign-out that silently signs you back in is not
             // a sign-out.
-            store.set(TRIED, '1');
+            await store.set(TRIED, '1');
         },
     };
 }

package/dist/config.d.ts

@@ -14,6 +14,15 @@ export interface AuthOptions {
     clientId: string | undefined;
     /** From scripts/provisioned.json. Sent as a scope and checked on every token. */
     organizationId: string | undefined;
+    /**
+     * Extra scopes appended to `scopeFor`'s fixed set, on both the
+     * authorization request `start` builds and the QR device grant --
+     * a project's `:aud` scope, say. Each entry is split on whitespace,
+     * empty entries dropped, and duplicates (against the fixed scopes and
+     * each other) removed. Default: none, and the scope string this SDK has
+     * always sent is unchanged, byte for byte.
+     */
+    extraScopes?: string[];
     /**
      * 32 bytes, base64 or hex: `openssl rand -base64 32`. One per app.
      *
@@ -57,6 +66,7 @@ export interface ResolvedOptions {
     appUrl: URL;
     clientId: string;
     organizationId: string;
+    extraScopes: string[];
     /**
      * Decoded on first access, not at resolve time.
      *

package/dist/config.js

@@ -41,6 +41,7 @@ export function resolveOptions(options) {
         appUrl,
         clientId: options.clientId,
         organizationId: options.organizationId,
+        extraScopes: options.extraScopes ?? [],
         get cookieKey() {
             cookieKey ??= decodeKey(options.cookieSecret);
             return cookieKey;

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-export { type Auth, type AuthRequest, type Gate, type GateRules, type Intent, type MaxAge, type NewUser, type PasskeyRegistrationResult, type PasskeyRegistrationStart, type PasskeySignInStart, type Prompt, type QrPollResult, type QrPollStatus, type QrSignInStart, type ReadResult, type ResetError, type SignInError, type SignInResult, type SignUpError, type SignUpResult, type SignedIn, type User, createAuth, } from './auth.js';
+export { type AccessTokenReason, type AccessTokenResult, type Auth, type AuthRequest, type Gate, type GateRules, type Intent, type MaxAge, type NewUser, type PasskeyRegistrationResult, type PasskeyRegistrationStart, type PasskeySignInStart, type Prompt, type QrPollResult, type QrPollStatus, type QrSignInStart, type ReadResult, type ResetError, type SignInError, type SignInResult, type SignUpError, type SignUpResult, type SignedIn, type User, createAuth, } from './auth.js';
 export { type AuthOptions, ISSUER } from './config.js';
 export type { SetCookie } from './cookies.js';
 export type { SessionRecord, SessionStore, SessionUpdate } from './sessions.js';

package/dist/namespace-browser.js

@@ -30,7 +30,9 @@ export function createNamespaceBrowserAuth(options, selection) {
         appOrigin: origin,
         redirectUri,
     });
-    const scope = options.scope ?? 'openid email profile offline_access';
+    const open = options.open ?? ((url) => window.location.assign(url));
+    const baseScope = options.scope ?? 'openid email profile offline_access';
+    const scope = [baseScope, ...(options.extraScopes ?? [])].join(' ');
     const scopes = new Set(scope.split(/\s+/).filter(Boolean));
     if (!scopes.has('openid') ||
         [...scopes].some((s) => s.startsWith('urn:zitadel:iam:org:') &&
@@ -100,7 +102,7 @@ export function createNamespaceBrowserAuth(options, selection) {
         }).toString();
         if (!ownsPending(transaction.state))
             throw new Error('Another sign-in replaced this attempt');
-        window.location.assign(url.href);
+        await open(url.href);
     };
     const completeSignIn = async (search = window.location.search) => {
         const reject = () => ({
@@ -205,6 +207,12 @@ export function createNamespaceBrowserAuth(options, selection) {
         currentSession,
         silentSignInAvailable,
         completeSignIn,
+        async refresh() {
+            // completeSignIn above never reads `token.refresh_token`, so this
+            // store never holds one to rotate: there is nothing offered here that
+            // isn't already true of every namespace session.
+            return { kind: 'no-refresh-token' };
+        },
         async trySilentSignIn(returnTo = window.location.pathname) {
             if (!silentSignInAvailable())
                 return false;
@@ -216,7 +224,9 @@ export function createNamespaceBrowserAuth(options, selection) {
             sessionStorage.removeItem(triedKey);
             await authorize(undefined, returnTo);
         },
-        forget() {
+        // Matches BrowserAuth.forget()'s Promise<void> signature; this path's
+        // storage is always synchronous, so there is nothing to await.
+        async forget() {
             sessionStorage.removeItem(tokenKey);
             sessionStorage.removeItem(txKey);
             sessionStorage.setItem(triedKey, '1');

package/dist/oidc.d.ts

@@ -9,12 +9,28 @@ export declare const ORG_CLAIM = "urn:zitadel:iam:user:resourceowner:id";
  * or a request more than a minute behind, still gets the real refusal.
  */
 export declare const ROTATION_CACHE_MS = 60000;
-/** The scopes every flow asks for: the code-exchange authorization request and the QR device grant alike. */
-export declare function scopeFor(organizationId: string): string;
+/**
+ * The scopes every flow asks for: the code-exchange authorization request
+ * and the QR device grant alike. `extraScopes` -- `AuthOptions.extraScopes`,
+ * passed straight through -- is appended after the fixed set: each entry is
+ * split on whitespace, empty entries dropped, and anything already present
+ * (in the fixed set or an earlier extra entry) skipped. With none, the
+ * result is exactly the fixed-set string, byte for byte.
+ */
+export declare function scopeFor(organizationId: string, extraScopes?: readonly string[]): string;
 export interface Tokens {
     idToken: string;
     refreshToken?: string;
     claims: jose.JWTPayload;
+    /**
+     * The issuer's own access token from this exchange or refresh grant.
+     * Never persisted to a cookie or a namespace record -- `tokensFrom` is the
+     * only place that reads it off the response; `Auth.accessToken` is the
+     * only public caller, and it reads this off a refresh grant it runs itself.
+     */
+    accessToken?: string;
+    /** Epoch ms `accessToken` expires at. Present exactly when `accessToken` is and the issuer sent `expires_in`. */
+    accessTokenExpiresAt?: number;
 }
 export declare class Oidc {
     private readonly options;

package/dist/oidc.js

@@ -9,16 +9,35 @@ export const ORG_CLAIM = 'urn:zitadel:iam:user:resourceowner:id';
  * or a request more than a minute behind, still gets the real refusal.
  */
 export const ROTATION_CACHE_MS = 60_000;
-/** The scopes every flow asks for: the code-exchange authorization request and the QR device grant alike. */
-export function scopeFor(organizationId) {
-    return [
+/**
+ * The scopes every flow asks for: the code-exchange authorization request
+ * and the QR device grant alike. `extraScopes` -- `AuthOptions.extraScopes`,
+ * passed straight through -- is appended after the fixed set: each entry is
+ * split on whitespace, empty entries dropped, and anything already present
+ * (in the fixed set or an earlier extra entry) skipped. With none, the
+ * result is exactly the fixed-set string, byte for byte.
+ */
+export function scopeFor(organizationId, extraScopes) {
+    const scopes = [
         'openid',
         'email',
         'profile',
         'offline_access',
         `urn:zitadel:iam:org:id:${organizationId}`,
         'urn:zitadel:iam:user:resourceowner',
-    ].join(' ');
+    ];
+    if (extraScopes?.length) {
+        const seen = new Set(scopes);
+        for (const entry of extraScopes) {
+            for (const scope of entry.split(/\s+/)) {
+                if (scope && !seen.has(scope)) {
+                    seen.add(scope);
+                    scopes.push(scope);
+                }
+            }
+        }
+    }
+    return scopes.join(' ');
 }
 export class Oidc {
     options;
@@ -67,7 +86,7 @@ export class Oidc {
             ...(create ? { prompt: 'create' } : prompt ? { prompt } : {}),
             ...(maxAge === undefined ? {} : { max_age: String(maxAge) }),
             redirect_uri: this.redirectUri.href,
-            scope: scopeFor(this.options.organizationId),
+            scope: scopeFor(this.options.organizationId, this.options.extraScopes),
             state,
             nonce,
             code_challenge: await client.calculatePKCECodeChallenge(codeVerifier),
@@ -129,10 +148,13 @@ export class Oidc {
             throw new AuthError('exchange', 'the issuer returned no id token');
         }
         this.assertOrganization(claims);
+        const expiresIn = response.expiresIn();
         return {
             idToken: response.id_token,
             refreshToken: response.refresh_token ?? previousRefreshToken,
             claims,
+            accessToken: response.access_token,
+            accessTokenExpiresAt: expiresIn === undefined ? undefined : Date.now() + expiresIn * 1000,
         };
     }
     async verify(idToken) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wtfalch/auth",
-  "version": "0.11.0",
+  "version": "0.12.0",
   "description": "Sign in against auth.wtfalch.dev: a server session for a Next.js app, and a browser client with silent single sign-on across subdomains.",
   "repository": {
     "type": "git",