@relyper/sp-auth 0.1.0 → 0.4.0

package/README.md

@@ -1,12 +1,8 @@
 # @relyper/sp-auth
 
-Service-provider side of Relyper identity: turn gateway headers into a typed
-principal, gate access by role, and keep the identity layer out of your
-application code.
-
-Built for services that sit behind the Relyper auth gateway. The package covers
-the parts every service provider repeats — header parsing, role gating, the
-`/me` contract, dev login — and leaves persistence to you.
+Relyper identity for a service provider. Register your app at the Relyper IdP,
+authenticate it with its client secret, and get a typed principal with role
+gating — without writing an OIDC client yourself.
 
 ```bash
 npm install @relyper/sp-auth
@@ -14,18 +10,49 @@ npm install @relyper/sp-auth
 
 Requires Node 20+. ESM only.
 
-## Quick start (Fastify)
+Two ways to establish who the user is, and they are not alternatives of equal
+standing:
+
+- **[OIDC login](#oidc-login)** — the app is a registered, confidential OIDC
+  client. Authorization Code Flow with PKCE, ID tokens verified against the
+  IdP's JWKS, sessions in encrypted cookies. **This is the one to use.**
+- **[Gateway headers](#gateway-headers)** — the app trusts identity headers set
+  by a trusted proxy. No secret, no signature, no verification. Only defensible
+  when the app is unreachable except through that gateway.
+
+On top of that, **[Relyper Coins](#relyper-coins)** lets an app spend from the
+central wallets, authenticating with the same client credentials as the login.
+
+## OIDC login
+
+### 1. Register the service provider
+
+In the Relyper IdP's admin UI under **OIDC Settings**: generate a client ID and
+a client secret, set the redirect URI to `https://your-app.example/auth/callback`,
+and list the application roles your app gates on under **Application Roles**.
+
+The IdP stores only an Argon2id hash of the secret, so it cannot be read back
+later. Copy it when it is generated.
+
+### 2. Register the plugin
 
 ```ts
 import Fastify from 'fastify';
-import { relyperAuth } from '@relyper/sp-auth/fastify';
+import { relyperOidcAuth } from '@relyper/sp-auth/oidc/fastify';
 
 const app = Fastify();
 
-await app.register(relyperAuth, {
+await app.register(relyperOidcAuth, {
+  issuer: process.env.RELYPER_OIDC_ISSUER,          // https://api.relyper.de
+  clientId: process.env.RELYPER_OIDC_CLIENT_ID,
+  clientSecret: process.env.RELYPER_OIDC_CLIENT_SECRET,
+  redirectUri: process.env.RELYPER_OIDC_REDIRECT_URI,
+  sessionSecret: process.env.SESSION_SECRET,        // 32+ chars, yours alone
+
   requiredRole: 'my_service_user',
   protect: (request) => request.url.startsWith('/api/'),
   meRoute: '/api/me',
+
   // Turn the IdP identity into your own user record.
   resolveUser: async (identity) => prisma.user.upsert({
     where: { idpSubject: identity.subject },
@@ -35,76 +62,136 @@ await app.register(relyperAuth, {
 });
 
 app.get('/api/cases', async (request) => {
-  request.relyperIdentity; // { subject, email, displayName, roles }
+  request.relyperIdentity; // { subject, email, displayName, roles, tenantId, teams }
   request.principal;       // whatever resolveUser returned
 });
 ```
 
-Declare the type of your own principal once:
+That registers three routes — `/auth/login`, `/auth/callback`, `/auth/logout` —
+and guards everything `protect` selects.
+
+`sessionSecret` is **not** the client secret. It is the key this app seals its
+own cookies with, it never leaves the process, and rotating it logs everyone out.
+
+### 3. Drive it from the browser
 
 ```ts
-declare module 'fastify' {
-  interface FastifyRequest {
-    principal: { id: string; email: string };
-  }
+import { fetchRelyperSession, startRelyperLogin, startRelyperLogout } from '@relyper/sp-auth/client';
+
+const session = await fetchRelyperSession<{ id: string; email: string }>();
+
+switch (session.status) {
+  case 'authenticated': return session.user;
+  case 'unauthenticated': return startRelyperLogin({ loginUrl: session.loginUrl });
+  case 'forbidden': return showNoAccessScreen(session.message);
+  case 'error': return showError();
 }
 ```
 
-## Without Fastify
+`startRelyperLogin` is a full navigation, not a fetch: the IdP has to be able to
+show its own login page and set its own cookie, which an XHR cannot do. It
+remembers the current path and returns the user there afterwards.
 
-The core is a pure function over headers — no framework, no I/O:
+### What the flow guarantees
 
-```ts
-import { createRelyperAuth } from '@relyper/sp-auth';
-
-const auth = createRelyperAuth({ requiredRole: 'my_service_user' });
-const result = auth.authenticate(request.headers); // Node headers or a fetch Headers object
+| Step | What is checked |
+| --- | --- |
+| `/auth/login` | Fresh `state`, `nonce` and PKCE verifier, sealed into a short-lived encrypted cookie |
+| `/auth/callback` | `state` matches this browser's login; no cookie means no callback |
+| Token exchange | `client_secret_basic` (or `_post`), with the PKCE verifier |
+| ID token | RS256 signature against the IdP's JWKS, plus `iss`, `aud`, `exp`, `nonce`, `azp`, `sub` |
+| Algorithms | Pinned, so `alg: none` and HMAC-with-public-key are refused |
+| UserInfo (optional) | `sub` must match the ID token's, or the response is discarded |
+| Role | Checked at login **and** on every request afterwards |
+| `returnTo` | Local paths only, so the login cannot become an open redirect |
+
+The client secret only ever travels from your server to the IdP's token
+endpoint. It never reaches the browser.
+
+### Sessions
+
+The session is a cookie sealed with `sessionSecret` — encrypted (JWE, direct
+A256GCM), not merely signed, so the browser cannot read the user's claims and
+tampering fails to decrypt rather than yielding a forged value. The login cookie
+and the session cookie use separate keys derived from that one secret, so
+neither can be replayed as the other.
+
+Sessions are stateless by default. That has one consequence worth knowing: a
+logout clears the cookie in the browser that asked, but a cookie copied
+beforehand keeps working until it expires. When that matters, keep a revocation
+list:
 
-if (!result.ok) {
-  return new Response(JSON.stringify({ error: result.message }), { status: result.status });
-}
-result.identity.subject;
+```ts
+await app.register(relyperOidcAuth, {
+  // ...
+  onLogin: (result, request, sessionId) => revocations.remember(sessionId),
+  onLogout: (sessionId) => revocations.revoke(sessionId),
+  isSessionRevoked: (sessionId) => revocations.isRevoked(sessionId)
+});
 ```
 
-`authenticate` never throws and never does I/O, which makes it easy to unit test
-and safe to call on every request.
+### Without Fastify
 
-## Browser client
+The client is framework-free:
 
 ```ts
-import { fetchRelyperSession } from '@relyper/sp-auth/client';
+import { createRelyperOidcClient } from '@relyper/sp-auth/oidc';
 
-const session = await fetchRelyperSession<{ id: string; email: string }>();
+const client = createRelyperOidcClient({ issuer, clientId, clientSecret, redirectUri });
 
-switch (session.status) {
-  case 'authenticated': return session.user;
-  case 'unauthenticated': return redirectToLogin();
-  case 'forbidden': return showNoAccessScreen();
-  case 'error': return showError();
-}
+// Start
+const { url, transaction } = await client.createAuthorizationRequest({ returnTo: '/cases/7' });
+// Persist `transaction` for this browser, then redirect to `url`.
+
+// Finish
+const { identity, claims, tokens } = await client.completeLogin({ query, transaction });
 ```
 
-No framework dependency. A Vue composable or React hook around it is a few lines.
+Every failure is a `RelyperOidcError` with a `code`, an HTTP `status`, a message
+safe to show a user, and a `detail` safe to log.
 
-## Options
+### OIDC options
 
 | Option | Default | Purpose |
 | --- | --- | --- |
-| `requiredRole` | – | Role(s) required for this service. Omit to only require an identity. |
-| `roleMatch` | `'any'` | With several required roles: one is enough, or all are needed. |
-| `requireEmail` | `true` | Set to `false` if your IdP does not send an address. |
-| `headerNames` | Relyper headers | Override individual header names for another gateway. |
-| `acceptForwardedHeaders` | `false` | Also accept `x-forwarded-*`. Off by default on purpose. |
-| `devAuth` | `false` | Local login without a gateway. Never enable in production. |
-| `unauthenticatedStatus` | `401` | Status when no identity arrives. |
-| `forbiddenStatus` | `403` | Status when the role is missing. |
-| `message` | per code | Fixed string or a function for the error message. |
-| `parseRoles` | comma-separated | Custom splitting of the roles header. |
-
-Fastify adapter additions: `protect`, `hook`, `resolveUser`, `principalKey`,
-`meRoute`, `meResponse`, `errorBody`, `onAuthFailure`, `warnOnDevAuth`.
-
-## Headers
+| `issuer` | – | Base URL of the IdP, as it appears in `iss`. Required. |
+| `clientId` / `clientSecret` | – | This app's registration. Required. |
+| `redirectUri` | – | Must match the registered URI byte for byte. Required. |
+| `sessionSecret` | – | Key for this app's own cookies, 32+ chars. Fastify adapter only. |
+| `scope` | `openid email profile roles tenant teams` | Requested scopes. |
+| `tokenEndpointAuthMethod` | from discovery | `client_secret_basic` or `client_secret_post`. |
+| `requiredRole` / `roleMatch` | – / `'any'` | Role gate. |
+| `requireEmail` | `true` | Refuse a login with no address. |
+| `useUserInfo` | `false` | Also call UserInfo; the Relyper IdP puts everything in the ID token. |
+| `clockToleranceSeconds` | `60` | Leeway for `exp` / `iat`. |
+| `discoveryTtlMs` | `3600000` | How long the discovery document is reused. |
+| `requestTimeoutMs` | `10000` | Timeout for every call to the IdP. |
+| `mapClaims` | `defaultClaimsToIdentity` | Custom claim mapping. |
+| `fetch` | global | Custom fetch, used for discovery, tokens, UserInfo and JWKS alike. |
+
+Fastify adapter additions: `sessionCookieName`, `loginCookieName`, `cookieDomain`,
+`cookiePath`, `cookieSecure`, `sessionTtlSeconds`, `sessionAbsoluteTtlSeconds`,
+`loginTtlSeconds`, `rollingSession`, `keepIdToken`, `loginPath`, `callbackPath`,
+`logoutPath`, `postLogoutRedirect`, `loginErrorRedirect`, `protect`, `hook`,
+`resolveUser`, `principalKey`, `meRoute`, `meResponse`,
+`redirectUnauthenticated`, `errorBody`, `onAuthFailure`, `onLogin`, `onLogout`,
+`isSessionRevoked`.
+
+## Gateway headers
+
+The original integration, for services behind a gateway that authenticates on
+their behalf.
+
+```ts
+import { relyperAuth } from '@relyper/sp-auth/fastify';
+
+await app.register(relyperAuth, {
+  requiredRole: 'my_service_user',
+  protect: (request) => request.url.startsWith('/api/'),
+  meRoute: '/api/me',
+  resolveUser
+});
+```
 
 | Header | Meaning |
 | --- | --- |
@@ -116,30 +203,90 @@ Fastify adapter additions: `protect`, `hook`, `resolveUser`, `principalKey`,
 Fallbacks when `acceptForwardedHeaders` is on: `x-forwarded-user`,
 `x-forwarded-email`, `x-forwarded-preferred-username`, `x-forwarded-groups`.
 
-## Security model — read this
+Options: `requiredRole`, `roleMatch`, `requireEmail`, `headerNames`,
+`acceptForwardedHeaders`, `devAuth`, `unauthenticatedStatus`, `forbiddenStatus`,
+`message`, `parseRoles`. Fastify additions: `protect`, `hook`, `resolveUser`,
+`principalKey`, `meRoute`, `meResponse`, `errorBody`, `onAuthFailure`,
+`warnOnDevAuth`.
 
-This package trusts headers. It does **not** verify a token or a signature. That
-is only safe when your service is unreachable except through a gateway that
-strips client-supplied `x-relyper-*` headers and sets them itself.
+The core is a pure function over headers — no framework, no I/O, never throws:
 
-If your service can be reached directly, anyone can send
-`x-relyper-roles: my_service_user` and be admitted. Two rules follow:
+```ts
+import { createRelyperAuth } from '@relyper/sp-auth';
+
+const auth = createRelyperAuth({ requiredRole: 'my_service_user' });
+const result = auth.authenticate(request.headers);
+if (!result.ok) return reply.code(result.status).send({ error: result.message });
+result.identity.subject;
+```
+
+### Security model — read this
+
+This path trusts headers. It verifies no token and no signature. It is only safe
+when the service is unreachable except through a gateway that **overwrites**
+client-supplied `x-relyper-*` headers rather than passing them through.
+
+If the service can be reached directly, anyone can send
+`x-relyper-roles: my_service_user` and be admitted. `acceptForwardedHeaders`
+widens that surface further, because `x-forwarded-*` is what any generic proxy
+sets — which is why it is off by default.
+
+Prefer the OIDC login. It needs no such assumption about the network.
+
+## Relyper Coins
+
+Relyper Coins are held centrally: the wallet at the identity provider is the
+single source of truth for what a user can spend across every Relyper product.
+A service provider never keeps its own balance.
+
+```ts
+import { createRelyperCoinsClient, coinsBaseUrlFromIssuer, RelyperCoinsError } from '@relyper/sp-auth/coins';
+
+const coins = createRelyperCoinsClient({
+  // The IdP publishes OIDC at the issuer root but mounts its API under /api.
+  baseUrl: coinsBaseUrlFromIssuer(process.env.RELYPER_OIDC_ISSUER),
+  clientId: process.env.RELYPER_OIDC_CLIENT_ID,
+  clientSecret: process.env.RELYPER_OIDC_CLIENT_SECRET
+});
+
+const wallet = await coins.getWallet(identity.subject);
+
+try {
+  await coins.debit({
+    subject: identity.subject,
+    amountRc: 5,
+    reason: 'assistant.question',
+    idempotencyKey: 'my-app:' + requestHash,   // a retry must not charge twice
+    product: 'my-app',
+    provider: 'openai',
+    model: 'gpt-x'
+  });
+} catch (error) {
+  if (error instanceof RelyperCoinsError && error.code === 'insufficient_funds') {
+    // error.balanceRc / error.requestedRc
+  }
+}
+```
 
-- Never expose the service port publicly without the gateway in front of it.
-- Never enable `devAuth` in production. It is off by default, and the Fastify
-  adapter logs a warning the first time it is used.
+The same client ID and secret as the OIDC login, so the IdP can attribute every
+debit to one registered app and an operator can allow or revoke coin spending
+per app. The app has to be ticked as **May consume Relyper Coins** in the IdP
+admin UI, or `debit` throws with code `coins_not_enabled`.
 
-Token verification against the Relyper IdP (JWT/JWKS) is planned for a later
-version behind the same API, so switching should not require changes in calling
-code.
+`debit` refuses to overdraw a wallet. Because the exact cost of a request is
+usually only known after the work is done, check the balance against an estimate
+first and debit the real amount afterwards.
 
 ## Design
 
-- `authenticate` is pure: headers in, result out. No database, no fetch, no throw.
+- The OIDC client does no I/O you did not ask for: discovery and JWKS are
+  fetched lazily, cached, and go through your `fetch` if you supply one.
 - Identity and application user stay separate. The package hands you a
   `RelyperIdentity`; `resolveUser` maps it to your own record. That boundary is
   what makes the package reusable across service providers.
-- `subject` is the IdP ID and never the primary key of your database.
+- `subject` is the IdP's ID and never the primary key of your database.
+- Errors carry a user-safe `message` and a separate `detail` for logs, so an
+  IdP's diagnostics never leak into a response.
 
 ## License
 

package/dist/client.d.ts

@@ -8,15 +8,20 @@ export type RelyperSession<TUser = RelyperIdentity> = {
     status: 'authenticated';
     user: TUser;
 }
-/** No identity passed through the gateway. Typically: login required. */
+/**
+ * Nobody is signed in. With the OIDC integration the server also names the
+ * route that starts a login; {@link startRelyperLogin} sends the browser there.
+ */
  | {
     status: 'unauthenticated';
     response: Response;
+    loginUrl: string;
 }
 /** Signed in, but without the role required for this service provider. */
  | {
     status: 'forbidden';
     response: Response;
+    message?: string;
 } | {
     status: 'error';
     response: Response;
@@ -30,8 +35,35 @@ export type FetchSessionOptions = {
     signal?: AbortSignal;
     /** Default: 'same-origin'. */
     credentials?: RequestCredentials;
+    /** Fallback when the server names no login route. Default: '/auth/login'. */
+    loginPath?: string;
 };
 export declare function fetchRelyperSession<TUser = RelyperIdentity>(options?: FetchSessionOptions): Promise<RelyperSession<TUser>>;
+export type StartLoginOptions = {
+    /** Route that starts the login. Default: '/auth/login'. */
+    loginUrl?: string;
+    /**
+     * Where to land after the login. Default: the current path including query
+     * and hash, so the user resumes exactly where the session ran out.
+     */
+    returnTo?: string;
+};
+/**
+ * Sends the browser into the OIDC login.
+ *
+ * A full navigation, not a fetch: the identity provider has to be able to show
+ * its own login page and set its own session cookie, which an XHR cannot do.
+ * `location.replace` keeps the expired page out of the back-button history.
+ */
+export declare function startRelyperLogin(options?: StartLoginOptions): void;
+/**
+ * Ends the session. A form POST rather than fetch, so the browser follows the
+ * server's redirect and, where the identity provider supports it, the logout
+ * continues on to end the session there too.
+ */
+export declare function startRelyperLogout(options?: {
+    logoutUrl?: string;
+}): void;
 /** true if the identity has at least one of the given roles. */
 export declare function hasAnyRole(identity: Pick<RelyperIdentity, 'roles'>, roles: string[]): boolean;
 export type { RelyperIdentity };

package/dist/client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAElD;;;;GAIG;AAEH,MAAM,MAAM,cAAc,CAAC,KAAK,GAAG,eAAe,IAC9C;IAAE,MAAM,EAAE,eAAe,CAAC;IAAC,IAAI,EAAE,KAAK,CAAA;CAAE;AAC1C,yEAAyE;GACvE;IAAE,MAAM,EAAE,iBAAiB,CAAC;IAAC,QAAQ,EAAE,QAAQ,CAAA;CAAE;AACnD,0EAA0E;GACxE;IAAE,MAAM,EAAE,WAAW,CAAC;IAAC,QAAQ,EAAE,QAAQ,CAAA;CAAE,GAC3C;IAAE,MAAM,EAAE,OAAO,CAAC;IAAC,QAAQ,EAAE,QAAQ,CAAA;CAAE,CAAC;AAE5C,MAAM,MAAM,mBAAmB,GAAG;IAChC,0BAA0B;IAC1B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,0DAA0D;IAC1D,KAAK,CAAC,EAAE,OAAO,UAAU,CAAC,KAAK,CAAC;IAChC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,8BAA8B;IAC9B,WAAW,CAAC,EAAE,kBAAkB,CAAC;CAClC,CAAC;AAEF,wBAAsB,mBAAmB,CAAC,KAAK,GAAG,eAAe,EAC/D,OAAO,GAAE,mBAAwB,GAChC,OAAO,CAAC,cAAc,CAAC,KAAK,CAAC,CAAC,CAkBhC;AAED,gEAAgE;AAChE,wBAAgB,UAAU,CAAC,QAAQ,EAAE,IAAI,CAAC,eAAe,EAAE,OAAO,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,OAAO,CAE7F;AAED,YAAY,EAAE,eAAe,EAAE,CAAC"}
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAElD;;;;GAIG;AAEH,MAAM,MAAM,cAAc,CAAC,KAAK,GAAG,eAAe,IAC9C;IAAE,MAAM,EAAE,eAAe,CAAC;IAAC,IAAI,EAAE,KAAK,CAAA;CAAE;AAC1C;;;GAGG;GACD;IAAE,MAAM,EAAE,iBAAiB,CAAC;IAAC,QAAQ,EAAE,QAAQ,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE;AACrE,0EAA0E;GACxE;IAAE,MAAM,EAAE,WAAW,CAAC;IAAC,QAAQ,EAAE,QAAQ,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAAE,GAC7D;IAAE,MAAM,EAAE,OAAO,CAAC;IAAC,QAAQ,EAAE,QAAQ,CAAA;CAAE,CAAC;AAE5C,MAAM,MAAM,mBAAmB,GAAG;IAChC,0BAA0B;IAC1B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,0DAA0D;IAC1D,KAAK,CAAC,EAAE,OAAO,UAAU,CAAC,KAAK,CAAC;IAChC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,8BAA8B;IAC9B,WAAW,CAAC,EAAE,kBAAkB,CAAC;IACjC,6EAA6E;IAC7E,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,CAAC;AAIF,wBAAsB,mBAAmB,CAAC,KAAK,GAAG,eAAe,EAC/D,OAAO,GAAE,mBAAwB,GAChC,OAAO,CAAC,cAAc,CAAC,KAAK,CAAC,CAAC,CAkChC;AAED,MAAM,MAAM,iBAAiB,GAAG;IAC9B,2DAA2D;IAC3D,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB,CAAC;AAEF;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,GAAE,iBAAsB,GAAG,IAAI,CASvE;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,GAAE;IAAE,SAAS,CAAC,EAAE,MAAM,CAAA;CAAO,GAAG,IAAI,CAS7E;AAED,gEAAgE;AAChE,wBAAgB,UAAU,CAAC,QAAQ,EAAE,IAAI,CAAC,eAAe,EAAE,OAAO,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,OAAO,CAE7F;AAUD,YAAY,EAAE,eAAe,EAAE,CAAC"}

package/dist/client.js

@@ -1,3 +1,4 @@
+const DEFAULT_LOGIN_PATH = '/auth/login';
 export async function fetchRelyperSession(options = {}) {
     const doFetch = options.fetch ?? globalThis.fetch;
     if (!doFetch)
@@ -5,21 +6,73 @@ export async function fetchRelyperSession(options = {}) {
     const response = await doFetch(options.path ?? '/api/me', {
         method: 'GET',
         credentials: options.credentials ?? 'same-origin',
+        // Without this the browser would follow a redirect to the identity provider
+        // inside the request, and the caller would see an opaque cross-origin
+        // failure instead of the status it can act on.
+        redirect: 'manual',
         headers: { accept: 'application/json', ...(options.headers ?? {}) },
         signal: options.signal
     });
-    if (response.status === 401)
-        return { status: 'unauthenticated', response };
-    if (response.status === 403)
-        return { status: 'forbidden', response };
+    if (response.status === 401 || response.type === 'opaqueredirect') {
+        const body = await readJsonBody(response);
+        const loginUrl = typeof body?.loginUrl === 'string' && body.loginUrl
+            ? body.loginUrl
+            : options.loginPath ?? DEFAULT_LOGIN_PATH;
+        return { status: 'unauthenticated', response, loginUrl };
+    }
+    if (response.status === 403) {
+        const body = await readJsonBody(response);
+        const message = typeof body?.error === 'string' ? body.error : undefined;
+        return { status: 'forbidden', response, message };
+    }
     if (!response.ok)
         return { status: 'error', response };
     const body = (await response.json());
     const user = body.user ?? body;
     return { status: 'authenticated', user };
 }
+/**
+ * Sends the browser into the OIDC login.
+ *
+ * A full navigation, not a fetch: the identity provider has to be able to show
+ * its own login page and set its own session cookie, which an XHR cannot do.
+ * `location.replace` keeps the expired page out of the back-button history.
+ */
+export function startRelyperLogin(options = {}) {
+    if (typeof window === 'undefined') {
+        throw new Error('@relyper/sp-auth/client: startRelyperLogin needs a browser environment.');
+    }
+    const base = options.loginUrl ?? DEFAULT_LOGIN_PATH;
+    const returnTo = options.returnTo
+        ?? window.location.pathname + window.location.search + window.location.hash;
+    const separator = base.includes('?') ? '&' : '?';
+    window.location.replace(base + separator + 'returnTo=' + encodeURIComponent(returnTo));
+}
+/**
+ * Ends the session. A form POST rather than fetch, so the browser follows the
+ * server's redirect and, where the identity provider supports it, the logout
+ * continues on to end the session there too.
+ */
+export function startRelyperLogout(options = {}) {
+    if (typeof window === 'undefined') {
+        throw new Error('@relyper/sp-auth/client: startRelyperLogout needs a browser environment.');
+    }
+    const form = window.document.createElement('form');
+    form.method = 'POST';
+    form.action = options.logoutUrl ?? '/auth/logout';
+    window.document.body.appendChild(form);
+    form.submit();
+}
 /** true if the identity has at least one of the given roles. */
 export function hasAnyRole(identity, roles) {
     return roles.some((role) => identity.roles.includes(role));
 }
+async function readJsonBody(response) {
+    try {
+        return (await response.clone().json());
+    }
+    catch {
+        return null;
+    }
+}
 //# sourceMappingURL=client.js.map

package/dist/client.js.map

@@ -1 +1 @@
-{"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AA2BA,MAAM,CAAC,KAAK,UAAU,mBAAmB,CACvC,OAAO,GAAwB,EAAE;IAEjC,MAAM,OAAO,GAAG,OAAO,CAAC,KAAK,IAAI,UAAU,CAAC,KAAK,CAAC;IAClD,IAAI,CAAC,OAAO;QAAE,MAAM,IAAI,KAAK,CAAC,6DAA6D,CAAC,CAAC;IAE7F,MAAM,QAAQ,GAAG,MAAM,OAAO,CAAC,OAAO,CAAC,IAAI,IAAI,SAAS,EAAE;QACxD,MAAM,EAAE,KAAK;QACb,WAAW,EAAE,OAAO,CAAC,WAAW,IAAI,aAAa;QACjD,OAAO,EAAE,EAAE,MAAM,EAAE,kBAAkB,EAAE,GAAG,CAAC,OAAO,CAAC,OAAO,IAAI,EAAE,CAAC,EAAE;QACnE,MAAM,EAAE,OAAO,CAAC,MAAM;KACvB,CAAC,CAAC;IAEH,IAAI,QAAQ,CAAC,MAAM,KAAK,GAAG;QAAE,OAAO,EAAE,MAAM,EAAE,iBAAiB,EAAE,QAAQ,EAAE,CAAC;IAC5E,IAAI,QAAQ,CAAC,MAAM,KAAK,GAAG;QAAE,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,QAAQ,EAAE,CAAC;IACtE,IAAI,CAAC,QAAQ,CAAC,EAAE;QAAE,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,QAAQ,EAAE,CAAC;IAEvD,MAAM,IAAI,GAAG,CAAC,MAAM,QAAQ,CAAC,IAAI,EAAE,CAA6B,CAAC;IACjE,MAAM,IAAI,GAAI,IAAyB,CAAC,IAAI,IAAK,IAAc,CAAC;IAChE,OAAO,EAAE,MAAM,EAAE,eAAe,EAAE,IAAI,EAAE,CAAC;AAC3C,CAAC;AAED,gEAAgE;AAChE,MAAM,UAAU,UAAU,CAAC,QAAwC,EAAE,KAAe;IAClF,OAAO,KAAK,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,QAAQ,CAAC,KAAK,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC;AAC7D,CAAC"}
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"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"}

package/dist/coins.d.ts

@@ -0,0 +1,139 @@
+/**
+ * Client for the Relyper Coins integration API.
+ *
+ * Relyper Coins are held centrally: the wallet at the identity provider is the
+ * single source of truth for what a user can spend across every Relyper product.
+ * A service provider therefore never keeps its own balance -- it asks, and it
+ * debits, and anything it stores locally is a mirror for its own reporting.
+ *
+ * The service provider authenticates with the same client ID and secret it uses
+ * for the OIDC login, so every debit is attributable to one registered client
+ * and an operator can allow or refuse coin spending per app.
+ */
+export type RelyperCoinWallet = {
+    ownerKind: 'user' | 'tenant';
+    ownerId: string;
+    balanceRc: number;
+    lifetimeEarnedRc: number;
+    lifetimeSpentRc: number;
+    reputationPoints: number;
+    convertibleRc: number;
+    planTier: string | null;
+    planMonthlyAllowanceRc: number;
+};
+export type RelyperCoinLedgerEntry = {
+    direction: 'credit' | 'debit';
+    amountRc: number;
+    balanceAfterRc: number;
+    reason: string;
+    product: string | null;
+    provider: string | null;
+    model: string | null;
+    clientId: string | null;
+    createdAt: string;
+};
+export type RelyperCoinDebit = {
+    /** IdP subject of the user, i.e. `identity.subject` from the login. */
+    subject: string;
+    amountRc: number;
+    /** Short machine-readable reason, e.g. 'assistant.question'. */
+    reason: string;
+    /**
+     * Makes the debit repeatable without double-charging. Strongly recommended:
+     * a retry after a timeout would otherwise bill the user twice.
+     */
+    idempotencyKey?: string;
+    /** Product label shown in the identity provider's reporting. */
+    product?: string;
+    provider?: string;
+    model?: string;
+    tenantId?: string;
+    meta?: Record<string, unknown>;
+};
+export type RelyperCoinDebitResult = {
+    wallet: RelyperCoinWallet;
+    entry: RelyperCoinLedgerEntry | null;
+    /** True when this idempotency key had already been booked; nothing was charged again. */
+    deduplicated: boolean;
+};
+export type RelyperCoinsErrorCode = 
+/** The wallet does not hold enough coins. */
+'insufficient_funds'
+/** This client is registered but not permitted to spend coins. */
+ | 'coins_not_enabled'
+/** Client credentials rejected. */
+ | 'unauthorized'
+/**
+ * Refused with 403 without saying it was the coin permission. Usually the
+ * request never reached the coins service: a wrong base URL, a gateway or a
+ * WAF. Read `url` and `responseBody` on the error.
+ */
+ | 'forbidden'
+/** The request was malformed. */
+ | 'invalid_request'
+/** The identity provider was unreachable or answered unexpectedly. */
+ | 'unavailable';
+export declare class RelyperCoinsError extends Error {
+    readonly code: RelyperCoinsErrorCode;
+    readonly status: number;
+    /** Present on insufficient_funds. */
+    readonly balanceRc?: number;
+    readonly requestedRc?: number;
+    readonly cause?: unknown;
+    /**
+     * What the service actually answered, and where it was asked.
+     *
+     * Kept because a status code alone does not identify a cause: a 403 from the
+     * coins service and a 403 from a proxy in front of it are the same number and
+     * mean entirely different things. Without the body, an operator holding a
+     * correctly configured client has nothing to go on but a message this library
+     * guessed. `responseError` is the service's own error code when it sent one.
+     */
+    readonly url?: string;
+    readonly responseError?: string;
+    readonly responseBody?: string;
+    constructor(code: RelyperCoinsErrorCode, message: string, options?: {
+        status?: number;
+        balanceRc?: number;
+        requestedRc?: number;
+        cause?: unknown;
+        url?: string;
+        responseError?: string;
+        responseBody?: string;
+    });
+}
+export type RelyperCoinsOptions = {
+    /**
+     * Base URL of the identity provider's API, including the path prefix its
+     * routes are mounted under. For Relyper that is the issuer plus `/api`, e.g.
+     * `https://api.relyper.de/api` for issuer `https://api.relyper.de`.
+     */
+    baseUrl: string;
+    /** Same credentials as the OIDC login. */
+    clientId: string;
+    clientSecret: string;
+    /** Default: 10000. */
+    requestTimeoutMs?: number;
+    fetch?: typeof globalThis.fetch;
+};
+export type RelyperCoinsClient = {
+    /** Balance and plan allowance of one user's wallet. */
+    getWallet(subject: string): Promise<RelyperCoinWallet>;
+    /** Recent ledger entries for one user. */
+    getLedger(subject: string, limit?: number): Promise<RelyperCoinLedgerEntry[]>;
+    /**
+     * Spends coins. Throws {@link RelyperCoinsError} with code `insufficient_funds`
+     * when the wallet cannot cover the amount -- the debit is refused, not
+     * overdrawn.
+     */
+    debit(input: RelyperCoinDebit): Promise<RelyperCoinDebitResult>;
+};
+/**
+ * Derives the coins API base URL from an OIDC issuer.
+ *
+ * The Relyper IdP publishes OIDC at the issuer root but mounts its regular API
+ * under `/api`, so the two differ by exactly that segment.
+ */
+export declare function coinsBaseUrlFromIssuer(issuer: string): string;
+export declare function createRelyperCoinsClient(options: RelyperCoinsOptions): RelyperCoinsClient;
+//# sourceMappingURL=coins.d.ts.map