@columenlabs/lumen-auth 0.0.0-stage → 0.1.32

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Columen Labs
+
+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/NOTICE

@@ -0,0 +1,12 @@
+Lumen
+Copyright (c) 2026 Columen Labs. Licensed under the MIT License (see LICENSE).
+
+Lumen draws price and market charts with TradingView Lightweight Charts™
+(https://github.com/tradingview/lightweight-charts), Copyright (c) 2025
+TradingView, Inc., licensed under the Apache License 2.0. Lumen turns off the
+chart's own logo, so per that library's NOTICE, an app that shows these charts
+should link to https://www.tradingview.com/ somewhere a user can find it (an
+About page or footer is enough).
+
+The components under packages/ui/src/ui are based on shadcn/ui
+(https://ui.shadcn.com), MIT License, Copyright (c) 2023 shadcn.

package/README.md

@@ -1,3 +1,49 @@
-# Temporary Holding Version
+# @columenlabs/lumen-auth
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Lumen's sign-in checks for Workers behind Cloudflare Access: verify the token Access signs on every request, in the Worker, so a route stays closed even when the Access application is misconfigured or a request reached the Worker another way. No dependencies: Web Crypto and `fetch`, so it runs in a Worker, Bun or Node.
+
+- Docs: https://lumen.columenlabs.com/docs/
+- For agents: https://lumen.columenlabs.com/llms.txt
+- Source: https://github.com/columenlabs/lumen (`packages/auth`). MIT.
+
+## Install
+
+```bash
+bun add @columenlabs/lumen-auth
+```
+
+Pin it to the same exact version as the other Lumen packages.
+
+## Verify an Access token
+
+```ts
+import { AccessVerifier, accessToken } from '@columenlabs/lumen-auth';
+
+// One per isolate: the team's signing keys are fetched once and kept an hour.
+const access = new AccessVerifier({
+  teamDomain: 'myteam.cloudflareaccess.com',
+  aud: [env.ACCESS_AUD],            // one application's AUD tag, or several (one Worker, several hosts)
+});
+
+const who = await access.verify(accessToken(request));
+if (!who) return new Response('Not found', { status: 404 });
+who.email;         // the person, when a person signed in
+who.serviceToken;  // the service token's client ID, when a service token signed in
+who.sub;           // Access's subject id
+```
+
+`verify` returns `null` for a missing, malformed, expired or wrongly signed token, a token for another application (`aud`) or another team (`iss`). Only RS256 is accepted. A key id it has not seen fetches the keys again.
+
+| Export | |
+|---|---|
+| `AccessVerifier(config, fetch?, now?)` | `verify(token)` → `AccessIdentity` or `null`. `fetch` and `now` are for tests |
+| `AccessConfig` | `{ teamDomain, aud }` |
+| `AccessIdentity` | `{ sub, email?, serviceToken? }` |
+| `accessToken(request)` | The request's `Cf-Access-Jwt-Assertion`, if any |
+| `ACCESS_HEADER` | `'cf-access-jwt-assertion'` |
+
+Who Access lets in stays Access's policy; what each person may do stays the app's own. This package only proves the request came through Access.
+
+## Versions
+
+0.x: any minor may break things until 1.0. Every merge to Lumen's `main` publishes the next patch of every Lumen package; see the [releases](https://github.com/columenlabs/lumen/releases).

package/dist/access.d.ts

@@ -0,0 +1,34 @@
+export interface AccessConfig {
+    /** e.g. `columenlabs.cloudflareaccess.com` */
+    teamDomain: string;
+    /** The Access application's AUD tag, or several applications' tags (one Worker on several hosts). */
+    aud: string | string[];
+}
+export interface AccessIdentity {
+    email?: string;
+    sub: string;
+    /** Service-token client ID (`common_name`) when an Access service token, not a person, signed in. */
+    serviceToken?: string;
+}
+type FetchFn = (input: string) => Promise<Response>;
+/** The header Access puts its signed token in. */
+export declare const ACCESS_HEADER = "cf-access-jwt-assertion";
+/** A request's Access token, if it has one. */
+export declare const accessToken: (request: Request) => string | undefined;
+/**
+ * Verifies Access tokens against the team's signing keys (fetched from
+ * `https://<teamDomain>/cdn-cgi/access/certs`, kept an hour, fetched again for an unknown key id):
+ * RS256 only, the audience one of `aud`, the issuer the team, not expired and not before its time.
+ * Keep one per isolate so the keys are fetched once.
+ */
+export declare class AccessVerifier {
+    private readonly cfg;
+    private readonly fetchImpl;
+    private readonly now;
+    private keys;
+    constructor(cfg: AccessConfig, fetchImpl?: FetchFn, now?: () => number);
+    private keyFor;
+    /** Returns the identity, or null when the token is missing/invalid. */
+    verify(token: string | undefined): Promise<AccessIdentity | null>;
+}
+export {};

package/dist/access.js

@@ -0,0 +1,93 @@
+// Cloudflare Access sign-in, checked again in the Worker. Access guards a host at the edge; the
+// Worker verifies its signed token (`Cf-Access-Jwt-Assertion`) on every request, so a route stays
+// closed even if the Access application is misconfigured or a request reached the Worker some
+// other way. No dependencies: Web Crypto and fetch only, so it runs in a Worker, Bun or Node.
+const b64urlToBytes = (s) => {
+    const b64 = s
+        .replace(/-/g, '+')
+        .replace(/_/g, '/')
+        .padEnd(Math.ceil(s.length / 4) * 4, '=');
+    const bin = atob(b64);
+    const out = new Uint8Array(bin.length);
+    for (let i = 0; i < bin.length; i++)
+        out[i] = bin.charCodeAt(i);
+    return out;
+};
+const decodeJson = (s) => JSON.parse(new TextDecoder().decode(b64urlToBytes(s)));
+/** The header Access puts its signed token in. */
+export const ACCESS_HEADER = 'cf-access-jwt-assertion';
+/** A request's Access token, if it has one. */
+export const accessToken = (request) => request.headers.get(ACCESS_HEADER) ?? undefined;
+/**
+ * Verifies Access tokens against the team's signing keys (fetched from
+ * `https://<teamDomain>/cdn-cgi/access/certs`, kept an hour, fetched again for an unknown key id):
+ * RS256 only, the audience one of `aud`, the issuer the team, not expired and not before its time.
+ * Keep one per isolate so the keys are fetched once.
+ */
+export class AccessVerifier {
+    cfg;
+    fetchImpl;
+    now;
+    keys;
+    constructor(cfg, fetchImpl = (u) => fetch(u), now = Date.now) {
+        this.cfg = cfg;
+        this.fetchImpl = fetchImpl;
+        this.now = now;
+    }
+    async keyFor(kid) {
+        const fresh = this.keys && this.now() - this.keys.at < 60 * 60_000;
+        if (!fresh || !this.keys?.keys.has(kid)) {
+            const res = await this.fetchImpl(`https://${this.cfg.teamDomain}/cdn-cgi/access/certs`);
+            if (!res.ok)
+                throw new Error(`access certs ${res.status}`);
+            const { keys } = (await res.json());
+            const map = new Map();
+            for (const k of keys) {
+                map.set(k.kid, await crypto.subtle.importKey('jwk', 
+                // JWK from Access's certs endpoint; the lib's JsonWebKey type isn't in scope here.
+                k, { name: 'RSASSA-PKCS1-v1_5', hash: 'SHA-256' }, false, ['verify']));
+            }
+            this.keys = { at: this.now(), keys: map };
+        }
+        return this.keys?.keys.get(kid);
+    }
+    /** Returns the identity, or null when the token is missing/invalid. */
+    async verify(token) {
+        if (!token)
+            return null;
+        const parts = token.split('.');
+        if (parts.length !== 3)
+            return null;
+        const [h, p, s] = parts;
+        try {
+            const header = decodeJson(h);
+            if (header.alg !== 'RS256')
+                return null;
+            const key = await this.keyFor(header.kid);
+            if (!key)
+                return null;
+            const ok = await crypto.subtle.verify('RSASSA-PKCS1-v1_5', key, b64urlToBytes(s), new Uint8Array(new TextEncoder().encode(`${h}.${p}`)));
+            if (!ok)
+                return null;
+            const claims = decodeJson(p);
+            const nowS = this.now() / 1000;
+            const auds = Array.isArray(claims.aud) ? claims.aud : [claims.aud];
+            const mine = Array.isArray(this.cfg.aud) ? this.cfg.aud : [this.cfg.aud];
+            if (!auds.some((a) => mine.includes(a)))
+                return null;
+            if (claims.iss !== `https://${this.cfg.teamDomain}`)
+                return null;
+            if (claims.exp < nowS || (claims.nbf !== undefined && claims.nbf > nowS + 60))
+                return null;
+            return {
+                sub: claims.sub,
+                email: claims.email,
+                // Service tokens carry no email; `common_name` is the token's client ID.
+                ...(claims.email || !claims.common_name ? {} : { serviceToken: claims.common_name }),
+            };
+        }
+        catch {
+            return null;
+        }
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1 @@
+export * from './access.js';

package/dist/index.js

@@ -0,0 +1 @@
+export * from './access.js';

package/package.json

@@ -1,6 +1,39 @@
 {
   "name": "@columenlabs/lumen-auth",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.32",
+  "description": "Lumen's sign-in checks: Cloudflare Access tokens and service tokens, verified in the Worker.",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./access": {
+      "types": "./dist/access.d.ts",
+      "default": "./dist/access.js"
+    }
+  },
+  "files": [
+    "dist",
+    "LICENSE",
+    "NOTICE"
+  ],
+  "sideEffects": [
+    "**/*.css"
+  ],
+  "homepage": "https://github.com/columenlabs/lumen",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/columenlabs/lumen.git",
+    "directory": "packages/auth"
+  },
+  "bugs": "https://github.com/columenlabs/lumen/issues",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "dependencies": {}
+}