@lunora/cloudflare-access 1.0.0-alpha.13 → 1.0.0-alpha.130

package/dist/packem_shared/types.d-Dp399TMk.d.mts

@@ -0,0 +1,280 @@
+import { JWTPayload, JWTVerifyGetKey, KeyObject } from 'jose';
+/**
+ * The subset of the Cloudflare `ExecutionContext` the Lunora worker entry and
+ * the framework mount seams rely on — `waitUntil` for fire-and-forget work that
+ * must outlive the response, and `passThroughOnException` for the top-level
+ * error posture.
+ *
+ * It is deliberately **not** a package. `@lunora/runtime` is the leaf server
+ * runtime and `@lunora/nuxt` is a framework integration that intentionally does
+ * not depend on `@lunora/runtime`'s worker types, yet both need this exact
+ * shape: the runtime to build/forward the worker `fetch`, Nuxt to forward an
+ * inbound request to the user's composed worker. Each imports this file by
+ * relative path and the bundler (packem/rollup) inlines it: no runtime
+ * dependency edge is created, the helper is duplicated only in emitted output,
+ * never in source. One source of truth, zero deps. See AGENTS.md → "Top-level
+ * `shared/` — bundler-inlined source".
+ *
+ * Both methods are **optional**: a real Cloudflare `ExecutionContext` always
+ * supplies them, but a host that mounts Lunora as a sub-handler (Nitro/H3, a
+ * non-Cloudflare preview, a unit test) may hand over a partial context or none
+ * at all. Callers therefore invoke them defensively (`ctx.waitUntil?.(…)`) or
+ * fall back to {@link NOOP_EXECUTION_CONTEXT}.
+ */
+interface ExecutionContextLike {
+  /**
+   * Present only when Cloudflare Access authenticated the request against a
+   * policy attached to the **Worker** (rather than to a hostname). `undefined`
+   * on every unauthenticated request, so its presence is itself the "Access
+   * authorized this caller" signal — see {@link AccessContextLike}.
+   */
+  access?: AccessContextLike;
+  cache?: {
+    purge: (options: {
+      purgeEverything?: boolean;
+      tags?: string[];
+    }) => Promise<unknown>;
+  };
+  passThroughOnException?: () => void;
+  waitUntil?: (promise: Promise<unknown>) => void;
+}
+/**
+ * The identity Cloudflare Access attaches to a Worker-protected request.
+ *
+ * Shape follows the Access application-token payload: `sub` is the stable per-user
+ * id, `email` the verified address, `common_name` the service-token name (machine
+ * callers, whose `sub` is empty), and `exp` the credential expiry in epoch
+ * **seconds**. Group membership is whatever the Access policy emits — a list of
+ * names, or of `{ id, name }` objects — hence `unknown`; normalize before use.
+ *
+ * Cloudflare may add further fields, so the index signature keeps them rather
+ * than dropping them: this is a view of a payload we do not own.
+ */
+interface AccessIdentityLike {
+  [claim: string]: unknown;
+  /** Service-token name. Present for non-interactive (machine) callers instead of `email`. */
+  common_name?: string;
+  /** Verified user email. Present for interactive (SSO) callers. */
+  email?: string;
+  /** Credential expiry, epoch **seconds**. */
+  exp?: number;
+  /** IdP group membership — names or `{ id, name }` objects, depending on the policy. */
+  groups?: unknown;
+  /** Display name from the identity provider, when it emits one. */
+  name?: string;
+  /** Stable per-user id, and what consumers key a user on. Empty for service tokens. */
+  sub?: string;
+  /** Cloudflare's per-user UUID. Carried through, but deliberately not used as an id — only this path emits it, so keying on it would not match the JWT path. */
+  user_uuid?: string;
+}
+/**
+ * The `ctx.access` facade Cloudflare exposes on a Worker protected by Access.
+ *
+ * Reading the identity from here is preferable to verifying the
+ * `Cf-Access-Jwt-Assertion` header: the platform has already authenticated the
+ * caller, so there is no JWKS fetch, no audience check to get wrong, and nothing
+ * a request can forge — the field simply does not exist unless Access authorized
+ * the call. The header path remains the fallback for hostname-scoped Access
+ * applications, which do not populate this.
+ */
+interface AccessContextLike {
+  getIdentity: () => AccessIdentityLike | null | undefined | Promise<AccessIdentityLike | null | undefined>;
+}
+/** A group→role(s) lookup table, or a function returning the role(s) for one group. */
+type AccessRoleMap = ((group: string) => string | string[] | undefined) | Record<string, string | string[]>;
+/**
+ * The verified claims of a Cloudflare Access caller — from the
+ * `Cf-Access-Jwt-Assertion` JWT (hostname-scoped Access applications) or from the
+ * platform-supplied `ctx.access.getIdentity()` (Access policies attached to the
+ * Worker). Both paths produce this one shape, so nothing downstream branches on
+ * how the caller was authenticated.
+ *
+ * Extends the standard `JWTPayload` (`iss`/`aud`/`sub`/`exp`/`iat`/…) with the
+ * Access-specific fields. Which optional fields are present depends on the
+ * caller and the Access application config. SSO users carry `email` (and
+ * `groups` when the policy emits them), with `sub` as the stable user id.
+ * Service tokens carry `common_name` and an empty `sub`; there is no `email`.
+ *
+ * Cloudflare may add further custom claims — they pass through verbatim via the
+ * index signature so the claims stay a faithful view of the identity.
+ */
+interface AccessClaims extends JWTPayload {
+  /** Service-token name. Present for non-interactive (machine) callers instead of `email`. */
+  common_name?: string;
+  /** ISO-3166-1 alpha-2 country the request was authorized from, when available. */
+  country?: string;
+  /** Verified user email. Present for interactive (SSO) callers. */
+  email?: string;
+  /** Identity-provider group memberships, when the Access policy is configured to emit them. */
+  groups?: string[];
+  /** Per-session nonce Cloudflare rotates on re-authentication. */
+  identity_nonce?: string;
+  /** Display name from the identity provider. Populated on the platform-supplied identity, not on the JWT. */
+  name?: string;
+  /** Token kind, e.g. `"app"`. */
+  type?: string;
+  /** Cloudflare's per-user UUID. Populated on the platform-supplied identity, not on the JWT — so `userId` is deliberately never derived from it. */
+  user_uuid?: string;
+}
+/**
+ * The minimal `resolveIdentity` return contract shared with `@lunora/runtime`'s
+ * `WorkerOptions.resolveIdentity` (`ResolvedIdentity`). Declared structurally so
+ * this package takes no runtime dependency on `@lunora/runtime`; the value is
+ * assignable to the runtime hook.
+ *
+ * `userId` becomes `ctx.auth.userId`; every other key is forwarded (server-side,
+ * unforgeable) into `x-lunora-identity` and surfaced via `ctx.auth.getIdentity()`.
+ * `exp` (JWT epoch **seconds**) drives WebSocket credential expiry — omit it and
+ * a live subscription socket never expires.
+ */
+interface ResolvedIdentityLike {
+  /** All other claims pass through into `ctx.auth.getIdentity()`. */
+  [claim: string]: unknown;
+  /** JWT `exp` in epoch **seconds** (NOT milliseconds). Drives WS socket expiry. */
+  exp?: number;
+  /** Absolute expiry in epoch **milliseconds**. Alternative to `exp`; takes precedence in the runtime. */
+  expiresAtMs?: number;
+  /** The stable caller id. Becomes `ctx.auth.userId` and what `serverDefault(({auth}) => auth.userId)` stamps. */
+  userId: string;
+}
+/**
+ * The verified Access identity produced by `createAccessResolver`. A
+ * {@link ResolvedIdentityLike} with the commonly-used Access claims promoted to
+ * named, camelCased fields (so policies read `auth.identity.groups` etc.) plus
+ * the full raw claim set under `access` for fidelity.
+ */
+interface ResolvedAccessIdentity extends ResolvedIdentityLike {
+  /** The full, verified claim set (snake_cased wire names preserved). */
+  access: AccessClaims;
+  /** Service-token name (`common_name`), for machine callers. */
+  commonName?: string;
+  /** Verified email, for SSO callers. */
+  email?: string;
+  /** IdP group memberships, when emitted by the Access policy. */
+  groups?: string[];
+}
+/**
+ * A key source for `verifyAccessJwt`. Either a `jose` remote/local JWKS getter,
+ * or a single public key (handy for tests that mint their own RS256 tokens).
+ * When omitted, a cached remote JWKS is built from `teamDomain`.
+ */
+type AccessKeySet = CryptoKey | JWTVerifyGetKey | KeyObject | Uint8Array;
+/** Options for `verifyAccessJwt`. */
+interface VerifyAccessJwtOptions {
+  /**
+   * The Access application **AUD tag(s)** (the application audience from the
+   * Access app's Overview). Verification rejects a token whose `aud` does not
+   * include one of these — this is what scopes a token to *your* app.
+   */
+  aud: string | string[];
+  /** Clock-skew tolerance in **seconds** applied to `exp`/`nbf`/`iat`. Default `0`. */
+  clockToleranceSec?: number;
+  /**
+   * Override the verification key source. Primarily for tests; in production
+   * leave unset to use the cached remote JWKS derived from `teamDomain`.
+   */
+  keySet?: AccessKeySet;
+  /**
+   * Your Cloudflare Access team domain. Accepts the short team name (`acme`),
+   * the host (`acme.cloudflareaccess.com`), or a full URL
+   * (`https://acme.cloudflareaccess.com`). Determines both the expected issuer
+   * and the JWKS endpoint.
+   */
+  teamDomain: string;
+}
+/**
+ * Common options for the request-driven Access primitives — how to read the JWT
+ * off the request and what to do when verification fails. Shared by
+ * {@link CreateAccessResolverOptions} and `AccessAdminGateOptions`, which add
+ * their distinct mapping / authorization step on top.
+ */
+interface RequestVerifyOptions extends VerifyAccessJwtOptions {
+  /**
+   * Cookie name carrying the Access JWT when the header is absent (browser
+   * navigations). Default `"CF_Authorization"`.
+   */
+  cookieName?: string;
+  /**
+   * Request header carrying the Access JWT. Default `"cf-access-jwt-assertion"`
+   * (matched case-insensitively).
+   */
+  headerName?: string;
+  /**
+   * Invoked when a token is present but fails verification (bad signature,
+   * wrong audience, expired, …). The caller still fails closed (resolver
+   * returns `null`, admin gate returns `false`); this is your hook to
+   * log/observe. It is **not** called when no token is present at all.
+   */
+  onError?: (error: unknown, request: Request) => void;
+}
+/**
+ * {@link RequestVerifyOptions} with the JWT-verification config made optional,
+ * for the primitives that can also authenticate off the platform-supplied
+ * identity (`ctx.access`) and therefore may legitimately be given no JWT config
+ * at all.
+ *
+ * The two fields are **all-or-nothing**: supply both to enable the
+ * `Cf-Access-Jwt-Assertion` fallback (needed for hostname-scoped Access
+ * applications, which do not populate `ctx.access`), or neither to run
+ * platform-identity-only. Supplying exactly one throws at construction — that is
+ * always a misconfiguration (classically an unset `env.CF_ACCESS_AUD`), and
+ * silently degrading it to "no JWT fallback" would turn a broken deployment into
+ * a quietly anonymous one.
+ */
+interface AccessJwtFallbackOptions extends Omit<RequestVerifyOptions, "aud" | "teamDomain"> {
+  /**
+   * The Access application **AUD tag(s)**. Required together with `teamDomain`
+   * to enable JWT verification; omit both to authenticate only off the
+   * platform-supplied identity.
+   */
+  aud?: string | string[];
+  /**
+   * Your Cloudflare Access team domain. Required together with `aud` to enable
+   * JWT verification; omit both to authenticate only off the platform-supplied
+   * identity.
+   */
+  teamDomain?: string;
+}
+/** Options for `createAccessResolver`; extends {@link AccessJwtFallbackOptions}. */
+interface CreateAccessResolverOptions extends AccessJwtFallbackOptions {
+  /**
+   * Remap verified claims into the resolved identity. Return an object to
+   * shallow-merge over the defaults; return a `userId` to override the derived
+   * caller id. Runs only after signature/issuer/audience/expiry are verified.
+   *
+   * It is merged OVER the `roles` claim {@link CreateAccessResolverOptions.roles}
+   * mints, so returning `roles` here replaces the mapped set outright.
+   */
+  mapClaims?: (claims: AccessClaims) => Record<string, unknown>;
+  /**
+   * Map the verified Access `groups` claim onto RLS role names, minted as the
+   * identity's `roles` claim — the list `rls()` unions permissions over.
+   *
+   * A table (`{ "idp-admins": "admin", "idp-eng": ["editor", "viewer"] }`) or a
+   * function; either may return one role, an array, or `undefined` to drop the
+   * group. Omit the option and no `roles` claim is minted at all — granting
+   * every group name as a role by default would hand existing deployments
+   * permissions their policies never intended. Pass `(group) => group` to opt
+   * into group names as role names verbatim.
+   *
+   * Roles live ON THE IDENTITY rather than being derived per-procedure so that
+   * every consumer sees the same set. A middleware that writes `ctx.auth.roles`
+   * reaches queries and mutations but NOT live shapes — a shape runs no
+   * procedure, so no middleware fires — and a role-gated policy then resolves
+   * differently for a query and the subscription that mirrors it. The identity
+   * is the one place both paths read.
+   */
+  roles?: AccessRoleMap;
+}
+/**
+ * A `resolveIdentity`-shaped function: maps an inbound request to a verified
+ * identity (or `null` for anonymous). Assignable to `@lunora/runtime`'s
+ * `WorkerOptions.resolveIdentity`.
+ *
+ * The third argument is the request's `ExecutionContext`, which the runtime
+ * forwards so a resolver can read the identity Cloudflare Access attaches to a
+ * Worker-protected request (`context.access`). It is `undefined` on paths that
+ * have no context to give, so a resolver must handle its absence.
+ */
+type ResolveIdentityFunction = (request: Request, env?: unknown, context?: ExecutionContextLike) => (ResolvedIdentityLike | null) | Promise<ResolvedIdentityLike | null>;
+export { AccessClaims as A, CreateAccessResolverOptions as C, ExecutionContextLike as E, ResolveIdentityFunction as R, VerifyAccessJwtOptions as V, AccessJwtFallbackOptions as a, AccessKeySet as b, AccessRoleMap as c, ResolvedAccessIdentity as d, ResolvedIdentityLike as e };

package/dist/packem_shared/types.d-Dp399TMk.d.ts

@@ -0,0 +1,280 @@
+import { JWTPayload, JWTVerifyGetKey, KeyObject } from 'jose';
+/**
+ * The subset of the Cloudflare `ExecutionContext` the Lunora worker entry and
+ * the framework mount seams rely on — `waitUntil` for fire-and-forget work that
+ * must outlive the response, and `passThroughOnException` for the top-level
+ * error posture.
+ *
+ * It is deliberately **not** a package. `@lunora/runtime` is the leaf server
+ * runtime and `@lunora/nuxt` is a framework integration that intentionally does
+ * not depend on `@lunora/runtime`'s worker types, yet both need this exact
+ * shape: the runtime to build/forward the worker `fetch`, Nuxt to forward an
+ * inbound request to the user's composed worker. Each imports this file by
+ * relative path and the bundler (packem/rollup) inlines it: no runtime
+ * dependency edge is created, the helper is duplicated only in emitted output,
+ * never in source. One source of truth, zero deps. See AGENTS.md → "Top-level
+ * `shared/` — bundler-inlined source".
+ *
+ * Both methods are **optional**: a real Cloudflare `ExecutionContext` always
+ * supplies them, but a host that mounts Lunora as a sub-handler (Nitro/H3, a
+ * non-Cloudflare preview, a unit test) may hand over a partial context or none
+ * at all. Callers therefore invoke them defensively (`ctx.waitUntil?.(…)`) or
+ * fall back to {@link NOOP_EXECUTION_CONTEXT}.
+ */
+interface ExecutionContextLike {
+  /**
+   * Present only when Cloudflare Access authenticated the request against a
+   * policy attached to the **Worker** (rather than to a hostname). `undefined`
+   * on every unauthenticated request, so its presence is itself the "Access
+   * authorized this caller" signal — see {@link AccessContextLike}.
+   */
+  access?: AccessContextLike;
+  cache?: {
+    purge: (options: {
+      purgeEverything?: boolean;
+      tags?: string[];
+    }) => Promise<unknown>;
+  };
+  passThroughOnException?: () => void;
+  waitUntil?: (promise: Promise<unknown>) => void;
+}
+/**
+ * The identity Cloudflare Access attaches to a Worker-protected request.
+ *
+ * Shape follows the Access application-token payload: `sub` is the stable per-user
+ * id, `email` the verified address, `common_name` the service-token name (machine
+ * callers, whose `sub` is empty), and `exp` the credential expiry in epoch
+ * **seconds**. Group membership is whatever the Access policy emits — a list of
+ * names, or of `{ id, name }` objects — hence `unknown`; normalize before use.
+ *
+ * Cloudflare may add further fields, so the index signature keeps them rather
+ * than dropping them: this is a view of a payload we do not own.
+ */
+interface AccessIdentityLike {
+  [claim: string]: unknown;
+  /** Service-token name. Present for non-interactive (machine) callers instead of `email`. */
+  common_name?: string;
+  /** Verified user email. Present for interactive (SSO) callers. */
+  email?: string;
+  /** Credential expiry, epoch **seconds**. */
+  exp?: number;
+  /** IdP group membership — names or `{ id, name }` objects, depending on the policy. */
+  groups?: unknown;
+  /** Display name from the identity provider, when it emits one. */
+  name?: string;
+  /** Stable per-user id, and what consumers key a user on. Empty for service tokens. */
+  sub?: string;
+  /** Cloudflare's per-user UUID. Carried through, but deliberately not used as an id — only this path emits it, so keying on it would not match the JWT path. */
+  user_uuid?: string;
+}
+/**
+ * The `ctx.access` facade Cloudflare exposes on a Worker protected by Access.
+ *
+ * Reading the identity from here is preferable to verifying the
+ * `Cf-Access-Jwt-Assertion` header: the platform has already authenticated the
+ * caller, so there is no JWKS fetch, no audience check to get wrong, and nothing
+ * a request can forge — the field simply does not exist unless Access authorized
+ * the call. The header path remains the fallback for hostname-scoped Access
+ * applications, which do not populate this.
+ */
+interface AccessContextLike {
+  getIdentity: () => AccessIdentityLike | null | undefined | Promise<AccessIdentityLike | null | undefined>;
+}
+/** A group→role(s) lookup table, or a function returning the role(s) for one group. */
+type AccessRoleMap = ((group: string) => string | string[] | undefined) | Record<string, string | string[]>;
+/**
+ * The verified claims of a Cloudflare Access caller — from the
+ * `Cf-Access-Jwt-Assertion` JWT (hostname-scoped Access applications) or from the
+ * platform-supplied `ctx.access.getIdentity()` (Access policies attached to the
+ * Worker). Both paths produce this one shape, so nothing downstream branches on
+ * how the caller was authenticated.
+ *
+ * Extends the standard `JWTPayload` (`iss`/`aud`/`sub`/`exp`/`iat`/…) with the
+ * Access-specific fields. Which optional fields are present depends on the
+ * caller and the Access application config. SSO users carry `email` (and
+ * `groups` when the policy emits them), with `sub` as the stable user id.
+ * Service tokens carry `common_name` and an empty `sub`; there is no `email`.
+ *
+ * Cloudflare may add further custom claims — they pass through verbatim via the
+ * index signature so the claims stay a faithful view of the identity.
+ */
+interface AccessClaims extends JWTPayload {
+  /** Service-token name. Present for non-interactive (machine) callers instead of `email`. */
+  common_name?: string;
+  /** ISO-3166-1 alpha-2 country the request was authorized from, when available. */
+  country?: string;
+  /** Verified user email. Present for interactive (SSO) callers. */
+  email?: string;
+  /** Identity-provider group memberships, when the Access policy is configured to emit them. */
+  groups?: string[];
+  /** Per-session nonce Cloudflare rotates on re-authentication. */
+  identity_nonce?: string;
+  /** Display name from the identity provider. Populated on the platform-supplied identity, not on the JWT. */
+  name?: string;
+  /** Token kind, e.g. `"app"`. */
+  type?: string;
+  /** Cloudflare's per-user UUID. Populated on the platform-supplied identity, not on the JWT — so `userId` is deliberately never derived from it. */
+  user_uuid?: string;
+}
+/**
+ * The minimal `resolveIdentity` return contract shared with `@lunora/runtime`'s
+ * `WorkerOptions.resolveIdentity` (`ResolvedIdentity`). Declared structurally so
+ * this package takes no runtime dependency on `@lunora/runtime`; the value is
+ * assignable to the runtime hook.
+ *
+ * `userId` becomes `ctx.auth.userId`; every other key is forwarded (server-side,
+ * unforgeable) into `x-lunora-identity` and surfaced via `ctx.auth.getIdentity()`.
+ * `exp` (JWT epoch **seconds**) drives WebSocket credential expiry — omit it and
+ * a live subscription socket never expires.
+ */
+interface ResolvedIdentityLike {
+  /** All other claims pass through into `ctx.auth.getIdentity()`. */
+  [claim: string]: unknown;
+  /** JWT `exp` in epoch **seconds** (NOT milliseconds). Drives WS socket expiry. */
+  exp?: number;
+  /** Absolute expiry in epoch **milliseconds**. Alternative to `exp`; takes precedence in the runtime. */
+  expiresAtMs?: number;
+  /** The stable caller id. Becomes `ctx.auth.userId` and what `serverDefault(({auth}) => auth.userId)` stamps. */
+  userId: string;
+}
+/**
+ * The verified Access identity produced by `createAccessResolver`. A
+ * {@link ResolvedIdentityLike} with the commonly-used Access claims promoted to
+ * named, camelCased fields (so policies read `auth.identity.groups` etc.) plus
+ * the full raw claim set under `access` for fidelity.
+ */
+interface ResolvedAccessIdentity extends ResolvedIdentityLike {
+  /** The full, verified claim set (snake_cased wire names preserved). */
+  access: AccessClaims;
+  /** Service-token name (`common_name`), for machine callers. */
+  commonName?: string;
+  /** Verified email, for SSO callers. */
+  email?: string;
+  /** IdP group memberships, when emitted by the Access policy. */
+  groups?: string[];
+}
+/**
+ * A key source for `verifyAccessJwt`. Either a `jose` remote/local JWKS getter,
+ * or a single public key (handy for tests that mint their own RS256 tokens).
+ * When omitted, a cached remote JWKS is built from `teamDomain`.
+ */
+type AccessKeySet = CryptoKey | JWTVerifyGetKey | KeyObject | Uint8Array;
+/** Options for `verifyAccessJwt`. */
+interface VerifyAccessJwtOptions {
+  /**
+   * The Access application **AUD tag(s)** (the application audience from the
+   * Access app's Overview). Verification rejects a token whose `aud` does not
+   * include one of these — this is what scopes a token to *your* app.
+   */
+  aud: string | string[];
+  /** Clock-skew tolerance in **seconds** applied to `exp`/`nbf`/`iat`. Default `0`. */
+  clockToleranceSec?: number;
+  /**
+   * Override the verification key source. Primarily for tests; in production
+   * leave unset to use the cached remote JWKS derived from `teamDomain`.
+   */
+  keySet?: AccessKeySet;
+  /**
+   * Your Cloudflare Access team domain. Accepts the short team name (`acme`),
+   * the host (`acme.cloudflareaccess.com`), or a full URL
+   * (`https://acme.cloudflareaccess.com`). Determines both the expected issuer
+   * and the JWKS endpoint.
+   */
+  teamDomain: string;
+}
+/**
+ * Common options for the request-driven Access primitives — how to read the JWT
+ * off the request and what to do when verification fails. Shared by
+ * {@link CreateAccessResolverOptions} and `AccessAdminGateOptions`, which add
+ * their distinct mapping / authorization step on top.
+ */
+interface RequestVerifyOptions extends VerifyAccessJwtOptions {
+  /**
+   * Cookie name carrying the Access JWT when the header is absent (browser
+   * navigations). Default `"CF_Authorization"`.
+   */
+  cookieName?: string;
+  /**
+   * Request header carrying the Access JWT. Default `"cf-access-jwt-assertion"`
+   * (matched case-insensitively).
+   */
+  headerName?: string;
+  /**
+   * Invoked when a token is present but fails verification (bad signature,
+   * wrong audience, expired, …). The caller still fails closed (resolver
+   * returns `null`, admin gate returns `false`); this is your hook to
+   * log/observe. It is **not** called when no token is present at all.
+   */
+  onError?: (error: unknown, request: Request) => void;
+}
+/**
+ * {@link RequestVerifyOptions} with the JWT-verification config made optional,
+ * for the primitives that can also authenticate off the platform-supplied
+ * identity (`ctx.access`) and therefore may legitimately be given no JWT config
+ * at all.
+ *
+ * The two fields are **all-or-nothing**: supply both to enable the
+ * `Cf-Access-Jwt-Assertion` fallback (needed for hostname-scoped Access
+ * applications, which do not populate `ctx.access`), or neither to run
+ * platform-identity-only. Supplying exactly one throws at construction — that is
+ * always a misconfiguration (classically an unset `env.CF_ACCESS_AUD`), and
+ * silently degrading it to "no JWT fallback" would turn a broken deployment into
+ * a quietly anonymous one.
+ */
+interface AccessJwtFallbackOptions extends Omit<RequestVerifyOptions, "aud" | "teamDomain"> {
+  /**
+   * The Access application **AUD tag(s)**. Required together with `teamDomain`
+   * to enable JWT verification; omit both to authenticate only off the
+   * platform-supplied identity.
+   */
+  aud?: string | string[];
+  /**
+   * Your Cloudflare Access team domain. Required together with `aud` to enable
+   * JWT verification; omit both to authenticate only off the platform-supplied
+   * identity.
+   */
+  teamDomain?: string;
+}
+/** Options for `createAccessResolver`; extends {@link AccessJwtFallbackOptions}. */
+interface CreateAccessResolverOptions extends AccessJwtFallbackOptions {
+  /**
+   * Remap verified claims into the resolved identity. Return an object to
+   * shallow-merge over the defaults; return a `userId` to override the derived
+   * caller id. Runs only after signature/issuer/audience/expiry are verified.
+   *
+   * It is merged OVER the `roles` claim {@link CreateAccessResolverOptions.roles}
+   * mints, so returning `roles` here replaces the mapped set outright.
+   */
+  mapClaims?: (claims: AccessClaims) => Record<string, unknown>;
+  /**
+   * Map the verified Access `groups` claim onto RLS role names, minted as the
+   * identity's `roles` claim — the list `rls()` unions permissions over.
+   *
+   * A table (`{ "idp-admins": "admin", "idp-eng": ["editor", "viewer"] }`) or a
+   * function; either may return one role, an array, or `undefined` to drop the
+   * group. Omit the option and no `roles` claim is minted at all — granting
+   * every group name as a role by default would hand existing deployments
+   * permissions their policies never intended. Pass `(group) => group` to opt
+   * into group names as role names verbatim.
+   *
+   * Roles live ON THE IDENTITY rather than being derived per-procedure so that
+   * every consumer sees the same set. A middleware that writes `ctx.auth.roles`
+   * reaches queries and mutations but NOT live shapes — a shape runs no
+   * procedure, so no middleware fires — and a role-gated policy then resolves
+   * differently for a query and the subscription that mirrors it. The identity
+   * is the one place both paths read.
+   */
+  roles?: AccessRoleMap;
+}
+/**
+ * A `resolveIdentity`-shaped function: maps an inbound request to a verified
+ * identity (or `null` for anonymous). Assignable to `@lunora/runtime`'s
+ * `WorkerOptions.resolveIdentity`.
+ *
+ * The third argument is the request's `ExecutionContext`, which the runtime
+ * forwards so a resolver can read the identity Cloudflare Access attaches to a
+ * Worker-protected request (`context.access`). It is `undefined` on paths that
+ * have no context to give, so a resolver must handle its absence.
+ */
+type ResolveIdentityFunction = (request: Request, env?: unknown, context?: ExecutionContextLike) => (ResolvedIdentityLike | null) | Promise<ResolvedIdentityLike | null>;
+export { AccessClaims as A, CreateAccessResolverOptions as C, ExecutionContextLike as E, ResolveIdentityFunction as R, VerifyAccessJwtOptions as V, AccessJwtFallbackOptions as a, AccessKeySet as b, AccessRoleMap as c, ResolvedAccessIdentity as d, ResolvedIdentityLike as e };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lunora/cloudflare-access",
-  "version": "1.0.0-alpha.13",
+  "version": "1.0.0-alpha.130",
   "description": "Cloudflare Access (Zero Trust) identity for Lunora — verify the Cf-Access-Jwt-Assertion JWT against your team JWKS and feed the verified identity into ctx.auth / RLS via a resolveIdentity adapter",
   "keywords": [
     "access",
@@ -44,21 +44,17 @@
       "types": "./dist/context.d.ts",
       "import": "./dist/context.mjs"
     },
-    "./roles": {
-      "types": "./dist/roles.d.ts",
-      "import": "./dist/roles.mjs"
-    },
     "./package.json": "./package.json"
   },
   "publishConfig": {
     "access": "public"
   },
   "dependencies": {
-    "@lunora/errors": "1.0.0-alpha.1",
-    "jose": "^6.2.3"
+    "@lunora/errors": "1.0.0-alpha.39",
+    "jose": "^6.2.12"
   },
   "peerDependencies": {
-    "@lunora/server": "1.0.0-alpha.16"
+    "@lunora/server": ">=1.0.0-alpha.24 <2.0.0-0"
   },
   "peerDependenciesMeta": {
     "@lunora/server": {