@willyim/idp 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Willy Ovalle
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,278 @@
+# @willyim/idp
+
+Login for apps that don't own identity.
+
+The [willy.im IdP](https://idp.willy.im) is the single source of truth for who
+someone is and what they may do. An app installing this package runs no auth
+framework: it owns one session table, which is a _handle_ to IdP truth rather
+than a record of it. No user table, no account table, no `ADMIN_EMAILS` list.
+
+Zero runtime dependencies — `fetch`, WebCrypto and `Request`/`Response` only, so
+the same build runs on Cloudflare Workers, Node 20+ and Bun.
+
+```
+@willyim/idp               core: OIDC client + server sessions
+@willyim/idp/drizzle       the session store, and the `idp_session` table
+@willyim/idp/react-router  the auth route and the loader guards
+```
+
+## Install
+
+```sh
+npm install @willyim/idp
+```
+
+`drizzle-orm` is an optional peer dependency, needed only by the `/drizzle`
+subpath. The `/react-router` subpath imports nothing at all — it just produces
+`Response`s.
+
+## Standard installation
+
+Four touch-points: a factory, a context wire-up, one route, one migration.
+
+**`app/lib/idp.server.ts`**
+
+```ts
+import { createIdp } from "@willyim/idp"
+import { drizzleSessions } from "@willyim/idp/drizzle"
+
+import * as schema from "~/db/schema"
+
+export function getIdp(env: AppEnv, db: AppDb) {
+  return createIdp({
+    issuer: "https://idp.willy.im/auth",
+    clientId: env.IDP_CLIENT_ID,
+    clientSecret: env.IDP_CLIENT_SECRET,
+    sessions: drizzleSessions(db, schema.idpSession),
+    session: { secret: env.SESSION_SECRET, expiresIn: "30d" },
+  })
+}
+
+export type Idp = ReturnType<typeof getIdp>
+```
+
+**`app/db/schema.ts`** — re-export the table so `drizzle-kit generate` sees it:
+
+```ts
+export { idpSession } from "@willyim/idp/drizzle"
+```
+
+**`workers/app.ts`** — built once per request, injected via load context:
+
+```ts
+const idp = getIdp(appEnv, db)
+const session = await idp.getSession(request)
+
+return requestHandler(request, {
+  env,
+  cloudflare: { env, ctx },
+  db,
+  services,
+  idp,
+  getSession: async () => {
+    if (!session) return null
+    const local = await db.query.owners.findFirst({ where: { email: session.email } })
+    return { sessionUser: session, currentUser: local ?? null, isAdmin: session.can("admin") }
+  },
+})
+```
+
+**`app/routes/auth.$.tsx`** — serves `/auth/login`, `/auth/callback`, `/auth/logout`:
+
+```ts
+import { createAuthRoute } from "@willyim/idp/react-router"
+
+export const { loader, action } = createAuthRoute(({ context }) => context.idp)
+```
+
+Then guard whatever needs guarding:
+
+```ts
+import { requirePermission, requireSession } from "@willyim/idp/react-router"
+
+export async function loader(args: Route.LoaderArgs) {
+  const session = await requireSession(args) // redirects to login, preserves ?next=
+  const admin = await requirePermission(args, "admin") // 403 without it
+}
+```
+
+## Env
+
+| Var                                   | Purpose                  |
+| ------------------------------------- | ------------------------ |
+| `IDP_CLIENT_ID` / `IDP_CLIENT_SECRET` | OIDC handshake           |
+| `SESSION_SECRET`                      | signs the session cookie |
+
+Register `https://your-app/auth/callback` as a redirect URI in the IdP console.
+
+## How a session works
+
+The cookie holds an **HMAC-signed opaque session id**. The signature is checked
+before the store is touched, so a junk cookie never costs a query. Everything
+else is in the row.
+
+`getSession`:
+
+```
+verify cookie signature      -> invalid/absent: null
+load row                     -> missing/expired: null
+now - syncedAt < freshness   -> return as-is                  (common path, one read)
+otherwise                    -> userinfo(accessToken)
+    access token expired     -> refresh first
+    401                      -> refresh, retry once
+    refresh fails            -> delete row, return null       (revoked at the IdP)
+    IdP unreachable          -> serve cached claims, retry next request
+    ok                       -> update claims + syncedAt, return
+```
+
+Permissions are a TTL-cached projection, not a login-time snapshot. A permission
+revoked at the IdP stops granting access within the freshness window — minutes,
+not session-lengths. The per-freshness `/userinfo` call doubles as a liveness
+ping, which is how revocation reaches the app.
+
+Instant revocation is a row delete: `idp.destroyAllSessions(sub)` logs a subject
+out of every browser on their next request.
+
+## Session lifetimes
+
+| Setting             | Default | Meaning                                                          |
+| ------------------- | ------- | ---------------------------------------------------------------- |
+| `expiresIn`         | `7d`    | idle timeout; slides on use                                      |
+| `updateAge`         | `1d`    | how far into its life a session must be before the expiry slides |
+| `freshness`         | `5m`    | how long cached claims are trusted                               |
+| `absoluteExpiresIn` | —       | hard cap measured from login                                     |
+
+When the IdP advertises a per-app ceiling (`session_max_age` in its discovery
+document), a longer `expiresIn` is clamped to it with a warning in development.
+No ceiling advertised, no clamp.
+
+Sliding the row past the browser cookie's own `Max-Age` needs one line: when the
+expiry moves, `session.renewCookie()` returns the `Set-Cookie` to attach.
+
+```ts
+const session = await idp.getSession(request)
+const renew = session?.renewCookie()
+if (renew) response.headers.append("set-cookie", renew)
+```
+
+## API
+
+### `createIdp(options)`
+
+```ts
+idp.getSession(request): Promise<Session | null>
+idp.startLogin({ redirectUri, next?, prompt?, loginHint? }): Promise<{ url, headers }>
+idp.completeLogin(request, { redirectUri }): Promise<{ session, headers, next }>
+idp.destroySession(request): Promise<Headers>
+idp.destroyAllSessions(sub): Promise<void>
+idp.logout(request, { redirectTo?, idpLogout? }): Promise<{ headers, url }>
+idp.client: IdpClient
+```
+
+`Session` carries claims and never tokens, so it is safe to project into loader
+data:
+
+```ts
+type Session = {
+  id: string
+  sub: string
+  email: string
+  name: string | null
+  image: string | null
+  permissions: string[]
+  workspaces: { id; slug; name; domain; role }[]
+  actor: { sub; email? } | null // RFC 8693 `act` — audit only, never authorize on it
+  createdAt: Date
+  expiresAt: Date
+  can(permission: string): boolean
+  renewCookie(): string | null
+}
+```
+
+`can()` matches exactly, and honours `resource:*` and `*` grants.
+
+### `createIdpClient(options)` — the OIDC relying party on its own
+
+```ts
+client.authorizationUrl({ redirectUri, state, codeChallenge, scopes?, prompt? }): Promise<string>
+client.exchangeCode({ code, redirectUri, codeVerifier }): Promise<Tokens>
+client.refresh(refreshToken): Promise<Tokens>
+client.userinfo(accessToken): Promise<Claims>
+client.logoutUrl({ idToken, redirectTo }): Promise<string | null>
+client.discover(): Promise<Discovery>
+```
+
+Discovery is derived from `issuer` and memoized per instance. PKCE is not
+optional. `Claims` arrive with the `https://willy.im/*` namespace unwrapped —
+`claims.permissions`, not `claims["https://willy.im/permissions"]`.
+
+### `@willyim/idp/drizzle`
+
+```ts
+idpSession                        // the SQLite/D1 table, named `idp_session`
+idpSessionSqliteTable(name?)      // …under another name
+idpSessionPgTable(name?)          // the Postgres equivalent
+drizzleSessions(db, table)        // -> SessionStore
+```
+
+### Session stores
+
+`SessionStore` is five methods, so swapping drizzle out is not a project:
+
+```ts
+type SessionStore = {
+  get(id): Promise<SessionRecord | null>
+  create(record): Promise<SessionRecord>
+  update(id, patch): Promise<SessionRecord | null>
+  delete(id): Promise<void>
+  deleteBySub(sub): Promise<void>
+}
+```
+
+`memorySessions()` ships for tests and single-process development.
+
+## Logout
+
+`/auth/logout` destroys the local session _first_, then redirects to the IdP's
+`end_session_endpoint` (read from discovery, never hardcoded) so the SSO session
+ends too. If that endpoint is unavailable the visitor simply lands back on the
+app — logout never leaves anyone signed in locally.
+
+RP-initiated logout needs the OAuth client registered for it at the IdP:
+
+- `enable_end_session` must be set, or the IdP answers `401 invalid_client`.
+- your post-logout URL must be listed in `post_logout_redirect_uris`, or the IdP
+  ends the session and leaves the visitor there.
+
+Until both are configured, pass `idpLogout: false` to `createAuthRoute` to keep
+logout app-local.
+
+## Testing
+
+Inject `fetch` and use the in-memory store; nothing needs the network.
+
+```ts
+const idp = createIdp({
+  issuer: "https://idp.test/auth",
+  clientId: "test",
+  clientSecret: "test",
+  fetch: stubbedFetch,
+  sessions: memorySessions(),
+  session: { secret: "test", secure: false },
+  now: () => clock, // the clock every session decision reads
+})
+```
+
+## Management API types
+
+The IdP's `/api/v1/*` management surface is not part of this package's public
+API in v1. The types for it are generated from the IdP's OpenAPI document —
+`npm run openapi` refreshes both `openapi/idp-api.json` and
+`src/generated/idp-api.d.ts` — so that when management calls are added they
+cannot be hand-written. The OIDC endpoints are not in that document and never
+will be: they are standards-defined and discovered at runtime from
+`.well-known`.
+
+## Licence
+
+MIT

package/dist/src/api.d.ts

@@ -0,0 +1,77 @@
+/**
+ * The typed door to the IdP's `/api/v1/*` management surface.
+ *
+ * Nothing in v1 goes through it — the management key, the directory API and
+ * end-user API keys were all cut — but it exists now so that the *first*
+ * management call can't be hand-written. Paths, methods, path parameters,
+ * request bodies and success shapes all come from `src/generated/idp-api.d.ts`,
+ * which `npm run openapi` regenerates from apps/idp's OpenAPI document. A typo
+ * in a path is a compile error, not a 404 in production.
+ *
+ * Deliberately not exported from any entrypoint: it is internal until the
+ * management surface is back in scope. Types only at runtime, so core stays
+ * dependency-free.
+ */
+import type { paths } from "./generated/idp-api.js";
+export type ApiPaths = paths;
+export type Method = "get" | "put" | "post" | "delete" | "patch";
+/** The paths that actually declare `M` — `paths` types the rest as `never`. */
+export type PathsFor<M extends Method> = {
+    [P in keyof paths]: paths[P] extends {
+        [K in M]: object;
+    } ? P : never;
+}[keyof paths];
+export type Operation<P extends keyof paths, M extends Method> = M extends keyof paths[P] ? paths[P][M] : never;
+type PathParams<O> = O extends {
+    parameters: {
+        path: infer T;
+    };
+} ? T extends object ? T : never : never;
+type RequestBody<O> = O extends {
+    requestBody: {
+        content: {
+            "application/json": infer B;
+        };
+    };
+} ? B : never;
+/** The 200 or 201 JSON body, whichever this operation declares. */
+type SuccessBody<O> = O extends {
+    responses: infer R;
+} ? R extends {
+    200: {
+        content: {
+            "application/json": infer T;
+        };
+    };
+} ? T : R extends {
+    201: {
+        content: {
+            "application/json": infer T;
+        };
+    };
+} ? T : never : never;
+export type RequestOptions<O> = ([PathParams<O>] extends [never] ? {
+    params?: undefined;
+} : {
+    params: PathParams<O>;
+}) & ([RequestBody<O>] extends [never] ? {
+    body?: undefined;
+} : {
+    body: RequestBody<O>;
+}) & {
+    query?: Record<string, string | number | boolean | undefined>;
+    signal?: AbortSignal;
+};
+export type ManagementApiOptions = {
+    /** IdP origin — the API lives at the root, not under the `/auth` basepath. */
+    baseUrl: string;
+    /** Superadmin `ADMIN_API_TOKEN` or a scoped `wim_…` key. */
+    token: string;
+    fetch?: typeof fetch;
+};
+export declare function createManagementApi(options: ManagementApiOptions): {
+    request<M extends Method, P extends PathsFor<M>>(method: M, path: P, init?: RequestOptions<Operation<P, M>>): Promise<SuccessBody<Operation<P, M>>>;
+};
+export type ManagementApi = ReturnType<typeof createManagementApi>;
+export {};
+//# sourceMappingURL=api.d.ts.map

package/dist/src/api.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"api.d.ts","sourceRoot":"","sources":["../../src/api.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAGH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,wBAAwB,CAAA;AAEnD,MAAM,MAAM,QAAQ,GAAG,KAAK,CAAA;AAC5B,MAAM,MAAM,MAAM,GAAG,KAAK,GAAG,KAAK,GAAG,MAAM,GAAG,QAAQ,GAAG,OAAO,CAAA;AAEhE,+EAA+E;AAC/E,MAAM,MAAM,QAAQ,CAAC,CAAC,SAAS,MAAM,IAAI;KACtC,CAAC,IAAI,MAAM,KAAK,GAAG,KAAK,CAAC,CAAC,CAAC,SAAS;SAAG,CAAC,IAAI,CAAC,GAAG,MAAM;KAAE,GAAG,CAAC,GAAG,KAAK;CACtE,CAAC,MAAM,KAAK,CAAC,CAAA;AAEd,MAAM,MAAM,SAAS,CAAC,CAAC,SAAS,MAAM,KAAK,EAAE,CAAC,SAAS,MAAM,IAAI,CAAC,SAAS,MAAM,KAAK,CAAC,CAAC,CAAC,GACrF,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GACX,KAAK,CAAA;AAET,KAAK,UAAU,CAAC,CAAC,IAAI,CAAC,SAAS;IAAE,UAAU,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC,CAAA;KAAE,CAAA;CAAE,GAC5D,CAAC,SAAS,MAAM,GACd,CAAC,GACD,KAAK,GACP,KAAK,CAAA;AAET,KAAK,WAAW,CAAC,CAAC,IAAI,CAAC,SAAS;IAAE,WAAW,EAAE;QAAE,OAAO,EAAE;YAAE,kBAAkB,EAAE,MAAM,CAAC,CAAA;SAAE,CAAA;KAAE,CAAA;CAAE,GACzF,CAAC,GACD,KAAK,CAAA;AAET,mEAAmE;AACnE,KAAK,WAAW,CAAC,CAAC,IAAI,CAAC,SAAS;IAAE,SAAS,EAAE,MAAM,CAAC,CAAA;CAAE,GAClD,CAAC,SAAS;IAAE,GAAG,EAAE;QAAE,OAAO,EAAE;YAAE,kBAAkB,EAAE,MAAM,CAAC,CAAA;SAAE,CAAA;KAAE,CAAA;CAAE,GAC7D,CAAC,GACD,CAAC,SAAS;IAAE,GAAG,EAAE;QAAE,OAAO,EAAE;YAAE,kBAAkB,EAAE,MAAM,CAAC,CAAA;SAAE,CAAA;KAAE,CAAA;CAAE,GAC7D,CAAC,GACD,KAAK,GACT,KAAK,CAAA;AAET,MAAM,MAAM,cAAc,CAAC,CAAC,IAAI,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,KAAK,CAAC,GAC5D;IAAE,MAAM,CAAC,EAAE,SAAS,CAAA;CAAE,GACtB;IAAE,MAAM,EAAE,UAAU,CAAC,CAAC,CAAC,CAAA;CAAE,CAAC,GAC5B,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,KAAK,CAAC,GAAG;IAAE,IAAI,CAAC,EAAE,SAAS,CAAA;CAAE,GAAG;IAAE,IAAI,EAAE,WAAW,CAAC,CAAC,CAAC,CAAA;CAAE,CAAC,GAAG;IACrF,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,SAAS,CAAC,CAAA;IAC7D,MAAM,CAAC,EAAE,WAAW,CAAA;CACrB,CAAA;AAEH,MAAM,MAAM,oBAAoB,GAAG;IACjC,8EAA8E;IAC9E,OAAO,EAAE,MAAM,CAAA;IACf,4DAA4D;IAC5D,KAAK,EAAE,MAAM,CAAA;IACb,KAAK,CAAC,EAAE,OAAO,KAAK,CAAA;CACrB,CAAA;AAED,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,oBAAoB;YAK/C,CAAC,SAAS,MAAM,EAAE,CAAC,SAAS,QAAQ,CAAC,CAAC,CAAC,UAC3C,CAAC,QACH,CAAC,SACD,cAAc,CAAC,SAAS,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GACpC,OAAO,CAAC,WAAW,CAAC,SAAS,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;EAkC3C;AAED,MAAM,MAAM,aAAa,GAAG,UAAU,CAAC,OAAO,mBAAmB,CAAC,CAAA"}

package/dist/src/api.js

@@ -0,0 +1,50 @@
+/**
+ * The typed door to the IdP's `/api/v1/*` management surface.
+ *
+ * Nothing in v1 goes through it — the management key, the directory API and
+ * end-user API keys were all cut — but it exists now so that the *first*
+ * management call can't be hand-written. Paths, methods, path parameters,
+ * request bodies and success shapes all come from `src/generated/idp-api.d.ts`,
+ * which `npm run openapi` regenerates from apps/idp's OpenAPI document. A typo
+ * in a path is a compile error, not a 404 in production.
+ *
+ * Deliberately not exported from any entrypoint: it is internal until the
+ * management surface is back in scope. Types only at runtime, so core stays
+ * dependency-free.
+ */
+import { IdpError } from "./client.js";
+export function createManagementApi(options) {
+    const baseUrl = options.baseUrl.replace(/\/+$/, "");
+    const doFetch = options.fetch ?? globalThis.fetch;
+    return {
+        async request(method, path, init = {}) {
+            const params = (init.params ?? {});
+            const rendered = String(path).replace(/\{([^}]+)\}/g, (_, name) => {
+                const value = params[name];
+                if (value === undefined)
+                    throw new Error(`missing path parameter "${name}" for ${path}`);
+                return encodeURIComponent(value);
+            });
+            const url = new URL(`${baseUrl}${rendered}`);
+            for (const [key, value] of Object.entries(init.query ?? {})) {
+                if (value !== undefined)
+                    url.searchParams.set(key, String(value));
+            }
+            const response = await doFetch(url.toString(), {
+                method: method.toUpperCase(),
+                signal: init.signal,
+                headers: {
+                    authorization: `Bearer ${options.token}`,
+                    accept: "application/json",
+                    ...(init.body === undefined ? {} : { "content-type": "application/json" }),
+                },
+                ...(init.body === undefined ? {} : { body: JSON.stringify(init.body) }),
+            });
+            const json = await response.json().catch(() => null);
+            if (!response.ok) {
+                throw new IdpError(`${method.toUpperCase()} ${rendered} failed (${response.status})`, response.status, json);
+            }
+            return json;
+        },
+    };
+}

package/dist/src/claims.d.ts

@@ -0,0 +1,46 @@
+/**
+ * The claim set the IdP hands back, with the `https://willy.im/*` namespace
+ * unwrapped. Namespaced URI claims are an OIDC requirement, not something app
+ * code should ever have to type — `claims.permissions`, not
+ * `claims["https://willy.im/permissions"]`.
+ */
+export declare const PERMISSIONS_CLAIM = "https://willy.im/permissions";
+export declare const WORKSPACES_CLAIM = "https://willy.im/workspaces";
+/** A tenant inside THIS app. `domain` is set for multi-domain apps, else null. */
+export type Workspace = {
+    id: string;
+    slug: string;
+    name: string;
+    domain: string | null;
+    role: string;
+};
+/**
+ * The RFC 8693 `act` claim: present while an IdP admin is impersonating the
+ * user. Audit-only — tag your logs with it, never branch authorization on it.
+ */
+export type Actor = {
+    sub: string;
+    email?: string;
+};
+export type Claims = {
+    sub: string;
+    email: string;
+    emailVerified: boolean;
+    name: string | null;
+    image: string | null;
+    /** Product permissions granted in this app. Unwrapped from the namespace. */
+    permissions: string[];
+    /** Workspaces the user belongs to in this app. Unwrapped from the namespace. */
+    workspaces: Workspace[];
+    actor: Actor | null;
+};
+/** Wire claims -> `Claims`. Tolerant: a missing claim is an empty value, not a throw. */
+export declare function normalizeClaims(payload: Record<string, unknown>): Claims;
+/**
+ * Does this permission set grant `permission`? Exact match, plus prefix
+ * wildcards — a grant of `invoices:*` covers `invoices:read`, and `*` covers
+ * everything. The IdP hands out concrete permissions today; the wildcard exists
+ * so an app-level catalog can group them without the SDK needing to know how.
+ */
+export declare function grants(permissions: readonly string[], permission: string): boolean;
+//# sourceMappingURL=claims.d.ts.map

package/dist/src/claims.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"claims.d.ts","sourceRoot":"","sources":["../../src/claims.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,eAAO,MAAM,iBAAiB,iCAAiC,CAAA;AAC/D,eAAO,MAAM,gBAAgB,gCAAgC,CAAA;AAE7D,kFAAkF;AAClF,MAAM,MAAM,SAAS,GAAG;IACtB,EAAE,EAAE,MAAM,CAAA;IACV,IAAI,EAAE,MAAM,CAAA;IACZ,IAAI,EAAE,MAAM,CAAA;IACZ,MAAM,EAAE,MAAM,GAAG,IAAI,CAAA;IACrB,IAAI,EAAE,MAAM,CAAA;CACb,CAAA;AAED;;;GAGG;AACH,MAAM,MAAM,KAAK,GAAG;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,CAAA;AAEnD,MAAM,MAAM,MAAM,GAAG;IACnB,GAAG,EAAE,MAAM,CAAA;IACX,KAAK,EAAE,MAAM,CAAA;IACb,aAAa,EAAE,OAAO,CAAA;IACtB,IAAI,EAAE,MAAM,GAAG,IAAI,CAAA;IACnB,KAAK,EAAE,MAAM,GAAG,IAAI,CAAA;IACpB,6EAA6E;IAC7E,WAAW,EAAE,MAAM,EAAE,CAAA;IACrB,gFAAgF;IAChF,UAAU,EAAE,SAAS,EAAE,CAAA;IACvB,KAAK,EAAE,KAAK,GAAG,IAAI,CAAA;CACpB,CAAA;AAED,yFAAyF;AACzF,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAqBxE;AAED;;;;;GAKG;AACH,wBAAgB,MAAM,CAAC,WAAW,EAAE,SAAS,MAAM,EAAE,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAOlF"}

package/dist/src/claims.js

@@ -0,0 +1,61 @@
+/**
+ * The claim set the IdP hands back, with the `https://willy.im/*` namespace
+ * unwrapped. Namespaced URI claims are an OIDC requirement, not something app
+ * code should ever have to type — `claims.permissions`, not
+ * `claims["https://willy.im/permissions"]`.
+ */
+export const PERMISSIONS_CLAIM = "https://willy.im/permissions";
+export const WORKSPACES_CLAIM = "https://willy.im/workspaces";
+/** Wire claims -> `Claims`. Tolerant: a missing claim is an empty value, not a throw. */
+export function normalizeClaims(payload) {
+    return {
+        sub: str(payload.sub) ?? "",
+        email: str(payload.email) ?? "",
+        emailVerified: payload.email_verified === true,
+        name: str(payload.name),
+        image: str(payload.picture) ?? str(payload.image),
+        permissions: Array.isArray(payload[PERMISSIONS_CLAIM])
+            ? payload[PERMISSIONS_CLAIM].map(String)
+            : [],
+        workspaces: Array.isArray(payload[WORKSPACES_CLAIM])
+            ? payload[WORKSPACES_CLAIM].map((w) => ({
+                id: String(w.id ?? ""),
+                slug: String(w.slug ?? ""),
+                name: String(w.name ?? ""),
+                domain: str(w.domain),
+                role: String(w.role ?? "member"),
+            }))
+            : [],
+        actor: actorOf(payload.act),
+    };
+}
+/**
+ * Does this permission set grant `permission`? Exact match, plus prefix
+ * wildcards — a grant of `invoices:*` covers `invoices:read`, and `*` covers
+ * everything. The IdP hands out concrete permissions today; the wildcard exists
+ * so an app-level catalog can group them without the SDK needing to know how.
+ */
+export function grants(permissions, permission) {
+    if (permissions.includes(permission) || permissions.includes("*"))
+        return true;
+    for (const granted of permissions) {
+        if (!granted.endsWith(":*"))
+            continue;
+        if (permission.startsWith(granted.slice(0, -1)))
+            return true;
+    }
+    return false;
+}
+function str(value) {
+    return typeof value === "string" && value ? value : null;
+}
+function actorOf(value) {
+    if (!value || typeof value !== "object")
+        return null;
+    const act = value;
+    const sub = str(act.sub);
+    if (!sub)
+        return null;
+    const email = str(act.email);
+    return email ? { sub, email } : { sub };
+}

package/dist/src/client.d.ts

@@ -0,0 +1,112 @@
+/**
+ * Layer 0 — the OIDC relying party. Everything on the wire lives here: the
+ * discovery document, the authorization-code flow with PKCE, refresh, userinfo,
+ * and RP-initiated logout. No sessions, no cookies, no storage.
+ *
+ * `fetch` + WebCrypto only, so it runs anywhere the platform is web-standard.
+ */
+import { type Claims } from "./claims.js";
+export declare const DEFAULT_SCOPES: string[];
+export type IdpClientOptions = {
+    /**
+     * The OIDC issuer, including the basepath the IdP is mounted on:
+     * `https://idp.willy.im/auth` (or a vanity domain, `https://idp.kasso.do/auth`).
+     * Discovery is `${issuer}/.well-known/openid-configuration`.
+     */
+    issuer: string;
+    clientId: string;
+    clientSecret: string;
+    /** Default scopes for `authorizationUrl`. `offline_access` buys refresh tokens. */
+    scopes?: string[];
+    /** Override `fetch` — tests, instrumentation, a Worker's bound fetcher. */
+    fetch?: typeof fetch;
+};
+/** The subset of the discovery document we use, plus the fields we may. */
+export type Discovery = {
+    issuer: string;
+    authorization_endpoint: string;
+    token_endpoint: string;
+    userinfo_endpoint: string;
+    end_session_endpoint?: string;
+    jwks_uri?: string;
+    /**
+     * Per-app session ceiling, in seconds. Not standard OIDC — an IdP extension
+     * the SDK clamps `session.expiresIn` against when present.
+     */
+    session_max_age?: number;
+};
+/** Token-endpoint output, camelCased so app code never sees the wire shape. */
+export type Tokens = {
+    accessToken: string;
+    tokenType: string;
+    /** Seconds until the access token expires, when the IdP says. */
+    expiresIn: number | null;
+    refreshToken: string | null;
+    idToken: string | null;
+    scope: string | null;
+};
+export declare class IdpError extends Error {
+    readonly status: number;
+    readonly body: unknown;
+    constructor(message: string, status: number, body?: unknown);
+}
+export type AuthorizationUrlInput = {
+    redirectUri: string;
+    state: string;
+    /** The S256 challenge. PKCE is not optional — see `createPkce`. */
+    codeChallenge: string;
+    scopes?: string[];
+    /** `login` to force re-authentication, `none` for a silent check. */
+    prompt?: string;
+    loginHint?: string;
+};
+export type IdpClient = ReturnType<typeof createIdpClient>;
+/** A fresh PKCE verifier and its S256 challenge. */
+export declare function createPkce(): Promise<{
+    codeVerifier: string;
+    codeChallenge: string;
+}>;
+export declare function createIdpClient(options: IdpClientOptions): {
+    discover: () => Promise<Discovery>;
+    /** Where to send the browser to log in. */
+    authorizationUrl(input: AuthorizationUrlInput): Promise<string>;
+    /** Swap the callback `code` for tokens. The verifier proves we started the flow. */
+    exchangeCode(input: {
+        code: string;
+        redirectUri: string;
+        codeVerifier: string;
+    }): Promise<Tokens>;
+    /** Requires `offline_access` at login. Throws `IdpError` once the grant is gone. */
+    refresh(refreshToken: string): Promise<Tokens>;
+    /**
+     * Live claims for an access token. Unlike the id_token — a login-time
+     * snapshot — this reflects permissions and workspaces as they are *now*,
+     * which is how a revocation at the IdP reaches the app.
+     */
+    userinfo(accessToken: string): Promise<Claims>;
+    /**
+     * RP-initiated logout, built from the `end_session_endpoint` in discovery —
+     * never a hardcoded path. Returns null when there is nothing usable to
+     * redirect to, which is either of:
+     *
+     *  - the IdP advertises no `end_session_endpoint`, or
+     *  - we have no `id_token` to hint with. The spec makes `id_token_hint`
+     *    optional; this IdP does not — it identifies the client from the hint,
+     *    verifies its signature, and reads `sid` out of it to pick the SSO
+     *    session to kill. Without one the request is rejected.
+     *
+     * Callers must treat null as "log out locally and move on" — see
+     * `createIdp().logout`, which does exactly that.
+     *
+     * Note the IdP-side registration this depends on: the OAuth client needs
+     * `enable_end_session` set (better-auth answers 401 `invalid_client`
+     * otherwise) and `redirectTo` must be listed in its
+     * `post_logout_redirect_uris` (an unlisted URI is silently not redirected
+     * to, leaving the visitor at the IdP).
+     */
+    logoutUrl(input: {
+        idToken?: string | null;
+        redirectTo?: string;
+    }): Promise<string | null>;
+};
+//# sourceMappingURL=client.d.ts.map

package/dist/src/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/client.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAmB,KAAK,MAAM,EAAE,MAAM,aAAa,CAAA;AAG1D,eAAO,MAAM,cAAc,UAAmD,CAAA;AAE9E,MAAM,MAAM,gBAAgB,GAAG;IAC7B;;;;OAIG;IACH,MAAM,EAAE,MAAM,CAAA;IACd,QAAQ,EAAE,MAAM,CAAA;IAChB,YAAY,EAAE,MAAM,CAAA;IACpB,mFAAmF;IACnF,MAAM,CAAC,EAAE,MAAM,EAAE,CAAA;IACjB,2EAA2E;IAC3E,KAAK,CAAC,EAAE,OAAO,KAAK,CAAA;CACrB,CAAA;AAED,2EAA2E;AAC3E,MAAM,MAAM,SAAS,GAAG;IACtB,MAAM,EAAE,MAAM,CAAA;IACd,sBAAsB,EAAE,MAAM,CAAA;IAC9B,cAAc,EAAE,MAAM,CAAA;IACtB,iBAAiB,EAAE,MAAM,CAAA;IACzB,oBAAoB,CAAC,EAAE,MAAM,CAAA;IAC7B,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB;;;OAGG;IACH,eAAe,CAAC,EAAE,MAAM,CAAA;CACzB,CAAA;AAED,+EAA+E;AAC/E,MAAM,MAAM,MAAM,GAAG;IACnB,WAAW,EAAE,MAAM,CAAA;IACnB,SAAS,EAAE,MAAM,CAAA;IACjB,iEAAiE;IACjE,SAAS,EAAE,MAAM,GAAG,IAAI,CAAA;IACxB,YAAY,EAAE,MAAM,GAAG,IAAI,CAAA;IAC3B,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;IACtB,KAAK,EAAE,MAAM,GAAG,IAAI,CAAA;CACrB,CAAA;AAED,qBAAa,QAAS,SAAQ,KAAK;IACjC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAA;gBACV,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO;CAM5D;AAED,MAAM,MAAM,qBAAqB,GAAG;IAClC,WAAW,EAAE,MAAM,CAAA;IACnB,KAAK,EAAE,MAAM,CAAA;IACb,mEAAmE;IACnE,aAAa,EAAE,MAAM,CAAA;IACrB,MAAM,CAAC,EAAE,MAAM,EAAE,CAAA;IACjB,qEAAqE;IACrE,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB,CAAA;AAED,MAAM,MAAM,SAAS,GAAG,UAAU,CAAC,OAAO,eAAe,CAAC,CAAA;AAE1D,oDAAoD;AACpD,wBAAsB,UAAU,IAAI,OAAO,CAAC;IAAE,YAAY,EAAE,MAAM,CAAC;IAAC,aAAa,EAAE,MAAM,CAAA;CAAE,CAAC,CAG3F;AAED,wBAAgB,eAAe,CAAC,OAAO,EAAE,gBAAgB;oBAOlC,OAAO,CAAC,SAAS,CAAC;IAiDrC,2CAA2C;4BACb,qBAAqB,GAAG,OAAO,CAAC,MAAM,CAAC;IAerE,oFAAoF;wBAChE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,CAAC;QAAC,YAAY,EAAE,MAAM,CAAA;KAAE;IAY/E,oFAAoF;0BAC9D,MAAM;IAO5B;;;;OAIG;0BACyB,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAepD;;;;;;;;;;;;;;;;;;;OAmBG;qBACoB;QACrB,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;QACvB,UAAU,CAAC,EAAE,MAAM,CAAA;KACpB,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;EAU7B"}