@lunora/cloudflare-access 0.0.1 → 1.0.0-alpha.2

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

@@ -0,0 +1,134 @@
+import { JWTPayload, JWTVerifyGetKey, KeyObject } from 'jose';
+/**
+* The claims Cloudflare Access mints into the `Cf-Access-Jwt-Assertion` JWT.
+*
+* 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 token.
+*/
+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;
+  /** Token kind, e.g. `"app"`. */
+  type?: 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;
+}
+/** Options for `createAccessResolver`; extends {@link RequestVerifyOptions}. */
+interface CreateAccessResolverOptions extends RequestVerifyOptions {
+  /**
+  * 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`.
+*/
+type ResolveIdentityFunction = (request: Request, env?: unknown) => (ResolvedIdentityLike | null) | Promise<ResolvedIdentityLike | null>;
+export { AccessClaims as A, CreateAccessResolverOptions as C, RequestVerifyOptions as R, VerifyAccessJwtOptions as V, ResolveIdentityFunction as a, AccessKeySet as b, ResolvedAccessIdentity as c, ResolvedIdentityLike as d };

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

@@ -0,0 +1,134 @@
+import { JWTPayload, JWTVerifyGetKey, KeyObject } from 'jose';
+/**
+* The claims Cloudflare Access mints into the `Cf-Access-Jwt-Assertion` JWT.
+*
+* 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 token.
+*/
+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;
+  /** Token kind, e.g. `"app"`. */
+  type?: 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;
+}
+/** Options for `createAccessResolver`; extends {@link RequestVerifyOptions}. */
+interface CreateAccessResolverOptions extends RequestVerifyOptions {
+  /**
+  * 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`.
+*/
+type ResolveIdentityFunction = (request: Request, env?: unknown) => (ResolvedIdentityLike | null) | Promise<ResolvedIdentityLike | null>;
+export { AccessClaims as A, CreateAccessResolverOptions as C, RequestVerifyOptions as R, VerifyAccessJwtOptions as V, ResolveIdentityFunction as a, AccessKeySet as b, ResolvedAccessIdentity as c, ResolvedIdentityLike as d };

package/dist/roles.d.mts

@@ -0,0 +1,52 @@
+import { M as Middleware } from "./packem_shared/index.d-C7lOF4ZA.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.
+*/
+interface AccessRolesContext {
+  auth?: {
+    getIdentity?: () => (Record<string, unknown> | null) | Promise<Record<string, unknown> | null>;
+    roles?: ReadonlyArray<string>;
+    userId?: string | null;
+  };
+}
+/** 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[]>;
+/** 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?: AccessRoleMap;
+  /**
+  * 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 }) => ...);
+* ```
+*/
+declare const accessRoles: <Context extends AccessRolesContext>(options?: AccessRolesOptions) => Middleware<Context, Context>;
+export { type AccessRoleMap, type AccessRolesContext, type AccessRolesOptions, accessRoles };

package/dist/roles.d.ts

@@ -0,0 +1,52 @@
+import { M as Middleware } from "./packem_shared/index.d-C7lOF4ZA.js";
+/**
+* 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>;
+    roles?: ReadonlyArray<string>;
+    userId?: string | null;
+  };
+}
+/** 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[]>;
+/** 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?: AccessRoleMap;
+  /**
+  * 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 }) => ...);
+* ```
+*/
+declare const accessRoles: <Context extends AccessRolesContext>(options?: AccessRolesOptions) => Middleware<Context, Context>;
+export { type AccessRoleMap, type AccessRolesContext, type AccessRolesOptions, accessRoles };

package/dist/roles.mjs

@@ -0,0 +1,35 @@
+const defaultReadGroups = (identity) => {
+  const { access } = identity;
+  const nested = typeof access === "object" && access !== null ? access.groups : void 0;
+  const groups = identity["groups"] ?? nested;
+  return Array.isArray(groups) ? groups.filter((group) => typeof group === "string") : void 0;
+};
+const rolesForGroup = (group, map) => {
+  if (map === void 0) {
+    return [group];
+  }
+  const resolved = typeof map === "function" ? map(group) : map[group];
+  if (resolved === void 0) {
+    return [];
+  }
+  return Array.isArray(resolved) ? resolved : [resolved];
+};
+const accessRoles = (options = {}) => {
+  const readGroups = options.readGroups ?? defaultReadGroups;
+  return async ({ ctx, next }) => {
+    const identity = await ctx.auth?.getIdentity?.() ?? void 0;
+    const groups = identity ? readGroups(identity) : void 0;
+    if (groups === void 0 || groups.length === 0) {
+      return next();
+    }
+    const roles = new Set(ctx.auth?.roles);
+    for (const group of groups) {
+      for (const role of rolesForGroup(group, options.map)) {
+        roles.add(role);
+      }
+    }
+    return next({ ctx: { auth: { ...ctx.auth, roles: [...roles] } } });
+  };
+};
+
+export { accessRoles };

package/package.json

@@ -1,10 +1,70 @@
 {
   "name": "@lunora/cloudflare-access",
-  "version": "0.0.1",
-  "description": "OIDC trusted publishing setup package for @lunora/cloudflare-access",
+  "version": "1.0.0-alpha.2",
+  "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": [
-    "oidc",
-    "trusted-publishing",
-    "setup"
-  ]
-}
+    "access",
+    "cloudflare",
+    "cloudflare-one",
+    "jwt",
+    "lunora",
+    "workers",
+    "zero-trust"
+  ],
+  "homepage": "https://lunora.sh",
+  "bugs": "https://github.com/anolilab/lunora/issues",
+  "license": "FSL-1.1-Apache-2.0",
+  "author": {
+    "name": "Daniel Bannert",
+    "email": "d.bannert@anolilab.de"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/anolilab/lunora.git",
+    "directory": "packages/cloudflare-access"
+  },
+  "files": [
+    "./dist",
+    "README.md",
+    "LICENSE.md",
+    "__assets__"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs"
+    },
+    "./admin": {
+      "types": "./dist/admin.d.ts",
+      "import": "./dist/admin.mjs"
+    },
+    "./context": {
+      "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": {
+    "jose": "^6.1.0"
+  },
+  "peerDependencies": {
+    "@lunora/server": "1.0.0-alpha.8"
+  },
+  "peerDependenciesMeta": {
+    "@lunora/server": {
+      "optional": true
+    }
+  },
+  "engines": {
+    "node": "^22.15.0 || >=24.11.0"
+  }
+}