@lunora/cloudflare-access 1.0.0-alpha.8 → 1.0.0-alpha.80

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

@@ -0,0 +1,256 @@
+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>;
+}
+/**
+ * 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.
+   */
+  mapClaims?: (claims: AccessClaims) => Record<string, unknown>;
+}
+/**
+ * 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, ResolvedAccessIdentity as c, ResolvedIdentityLike as d };

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

@@ -0,0 +1,256 @@
+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>;
+}
+/**
+ * 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.
+   */
+  mapClaims?: (claims: AccessClaims) => Record<string, unknown>;
+}
+/**
+ * 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, ResolvedAccessIdentity as c, ResolvedIdentityLike as d };

package/dist/roles.d.mts

@@ -1,11 +1,10 @@
-import { M as Middleware } from "./packem_shared/index.d-ByAnpUzP.mjs";
-import '@lunora/errors';
+import { M as Middleware } from "./packem_shared/index.d-D7R8k7yf.mjs";
 /**
-* The slice of context {@link accessRoles} reads and augments: the `auth` facade
-* every Lunora ctx carries. `getIdentity()` returns the verified identity
-* envelope (`createAccessResolver`'s output, including `groups`); `roles` is the
-* per-request role list `rls()` unions permissions over.
-*/
+ * The slice of context {@link accessRoles} reads and augments: the `auth` facade
+ * every Lunora ctx carries. `getIdentity()` returns the verified identity
+ * envelope (`createAccessResolver`'s output, including `groups`); `roles` is the
+ * per-request role list `rls()` unions permissions over.
+ */
 interface AccessRolesContext {
   auth?: {
     getIdentity?: () => (Record<string, unknown> | null) | Promise<Record<string, unknown> | null>;
@@ -18,36 +17,36 @@ type AccessRoleMap = ((group: string) => string | string[] | undefined) | Record
 /** Options for {@link accessRoles}. */
 interface AccessRolesOptions {
   /**
-  * Map verified Access group names to RLS role names. 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 to use each group name verbatim as a role.
-  */
+   * Map verified Access group names to RLS role names. 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 to use each group name verbatim as a role.
+   */
   map?: AccessRoleMap;
   /**
-  * Read the group list off the resolved identity. Defaults to the `groups`
-  * claim (`string[]`). Override when your IdP nests groups elsewhere.
-  */
+   * Read the group list off the resolved identity. Defaults to the `groups`
+   * claim (`string[]`). Override when your IdP nests groups elsewhere.
+   */
   readGroups?: (identity: Record<string, unknown>) => ReadonlyArray<string> | undefined;
 }
 /**
-* Middleware that lifts the verified Cloudflare Access `groups` claim into
-* `ctx.auth.roles` so `rls()` policies can authorize by role. Place it **before**
-* `rls(...)` in the `.use(...)` chain — `rls()` reads `ctx.auth.roles` to union
-* the permissions a request carries.
-*
-* It reads the resolved identity via `ctx.auth.getIdentity()` (the output of
-* `createAccessResolver`), maps each group to role name(s), and unions them with
-* any roles already on `ctx.auth.roles` (so a role set by an earlier middleware
-* is preserved). When there is no identity or no groups it forwards the context
-* unchanged — anonymous requests stay role-less (fail-closed under RLS).
-*
-* ```ts
-* export const listInvoices = query
-*   .use(accessRoles({ map: { "idp-admins": "admin", "idp-billing": ["billing", "viewer"] } }))
-*   .use(rls(policies, { roles }))
-*   .query(async ({ ctx }) => ...);
-* ```
-*/
+ * Middleware that lifts the verified Cloudflare Access `groups` claim into
+ * `ctx.auth.roles` so `rls()` policies can authorize by role. Place it **before**
+ * `rls(...)` in the `.use(...)` chain — `rls()` reads `ctx.auth.roles` to union
+ * the permissions a request carries.
+ *
+ * It reads the resolved identity via `ctx.auth.getIdentity()` (the output of
+ * `createAccessResolver`), maps each group to role name(s), and unions them with
+ * any roles already on `ctx.auth.roles` (so a role set by an earlier middleware
+ * is preserved). When there is no identity or no groups it forwards the context
+ * unchanged — anonymous requests stay role-less (fail-closed under RLS).
+ *
+ * ```ts
+ * export const listInvoices = query
+ *   .use(accessRoles({ map: { "idp-admins": "admin", "idp-billing": ["billing", "viewer"] } }))
+ *   .use(rls(policies, { roles }))
+ *   .query(async ({ ctx }) => ...);
+ * ```
+ */
 declare const accessRoles: <Context extends AccessRolesContext>(options?: AccessRolesOptions) => Middleware<Context, Context>;
 export { type AccessRoleMap, type AccessRolesContext, type AccessRolesOptions, accessRoles };