gazetta 0.6.0 → 0.8.0

package/dist/auth/providers/azure-easy-auth.js

@@ -0,0 +1,48 @@
+import { AuthenticationError } from '../errors.js';
+import { expandRole } from '../capabilities.js';
+const NAMEID_CLAIM = 'http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier';
+const EMAIL_CLAIM = 'http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress';
+export function createAzureEasyAuthProvider(config = {}) {
+    const defaultRole = config.defaultRole ?? 'editor';
+    return {
+        trustMode: 'azure-easy-auth',
+        async extractPrincipal(req) {
+            const encoded = req.headers.get('x-ms-client-principal');
+            if (!encoded || encoded.length === 0) {
+                // No identity header — anonymous. Easy Auth is configured
+                // to require auth; reaching Gazetta without the header
+                // means the request bypassed the platform (only possible
+                // if the operator misconfigured).
+                return null;
+            }
+            let parsed;
+            try {
+                const json = Buffer.from(encoded, 'base64').toString('utf-8');
+                parsed = JSON.parse(json);
+            }
+            catch (err) {
+                throw new AuthenticationError(`X-MS-CLIENT-PRINCIPAL header is not valid base64-encoded JSON: ${err.message}`);
+            }
+            if (!parsed || typeof parsed !== 'object' || !Array.isArray(parsed.claims)) {
+                throw new AuthenticationError('X-MS-CLIENT-PRINCIPAL is malformed (missing claims array)');
+            }
+            // Prefer X-MS-CLIENT-PRINCIPAL-ID when present (stable id);
+            // fall back to the nameidentifier claim.
+            const idHeader = req.headers.get('x-ms-client-principal-id');
+            const nameIdClaim = parsed.claims.find(c => c.typ === NAMEID_CLAIM)?.val;
+            const id = idHeader ?? nameIdClaim;
+            if (!id) {
+                throw new AuthenticationError('X-MS-CLIENT-PRINCIPAL has no nameidentifier claim and no X-MS-CLIENT-PRINCIPAL-ID');
+            }
+            const email = parsed.claims.find(c => c.typ === EMAIL_CLAIM)?.val;
+            return {
+                id,
+                email,
+                role: defaultRole,
+                trustMode: 'azure-easy-auth',
+                capabilities: expandRole(defaultRole) ?? [],
+            };
+        },
+    };
+}
+//# sourceMappingURL=azure-easy-auth.js.map

package/dist/auth/providers/azure-easy-auth.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"azure-easy-auth.js","sourceRoot":"","sources":["../../../src/auth/providers/azure-easy-auth.ts"],"names":[],"mappings":"AAsDA,OAAO,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAA;AAClD,OAAO,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAA;AAiB/C,MAAM,YAAY,GAAG,sEAAsE,CAAA;AAC3F,MAAM,WAAW,GAAG,oEAAoE,CAAA;AAExF,MAAM,UAAU,2BAA2B,CAAC,SAA8B,EAAE;IAC1E,MAAM,WAAW,GAAG,MAAM,CAAC,WAAW,IAAI,QAAQ,CAAA;IAClD,OAAO;QACL,SAAS,EAAE,iBAAiB;QAC5B,KAAK,CAAC,gBAAgB,CAAC,GAAgB;YACrC,MAAM,OAAO,GAAG,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,uBAAuB,CAAC,CAAA;YACxD,IAAI,CAAC,OAAO,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;gBACrC,0DAA0D;gBAC1D,uDAAuD;gBACvD,yDAAyD;gBACzD,kCAAkC;gBAClC,OAAO,IAAI,CAAA;YACb,CAAC;YAED,IAAI,MAA4B,CAAA;YAChC,IAAI,CAAC;gBACH,MAAM,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAA;gBAC7D,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAyB,CAAA;YACnD,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACb,MAAM,IAAI,mBAAmB,CAC3B,kEAAmE,GAAa,CAAC,OAAO,EAAE,CAC3F,CAAA;YACH,CAAC;YAED,IAAI,CAAC,MAAM,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,MAAM,CAAC,EAAE,CAAC;gBAC3E,MAAM,IAAI,mBAAmB,CAAC,2DAA2D,CAAC,CAAA;YAC5F,CAAC;YAED,4DAA4D;YAC5D,yCAAyC;YACzC,MAAM,QAAQ,GAAG,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,0BAA0B,CAAC,CAAA;YAC5D,MAAM,WAAW,GAAG,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,KAAK,YAAY,CAAC,EAAE,GAAG,CAAA;YACxE,MAAM,EAAE,GAAG,QAAQ,IAAI,WAAW,CAAA;YAClC,IAAI,CAAC,EAAE,EAAE,CAAC;gBACR,MAAM,IAAI,mBAAmB,CAC3B,mFAAmF,CACpF,CAAA;YACH,CAAC;YAED,MAAM,KAAK,GAAG,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,KAAK,WAAW,CAAC,EAAE,GAAG,CAAA;YAEjE,OAAO;gBACL,EAAE;gBACF,KAAK;gBACL,IAAI,EAAE,WAAW;gBACjB,SAAS,EAAE,iBAAiB;gBAC5B,YAAY,EAAE,UAAU,CAAC,WAAW,CAAC,IAAI,EAAE;aAC5C,CAAA;QACH,CAAC;KACF,CAAA;AACH,CAAC"}

package/dist/auth/providers/cloudflare-access.d.ts

@@ -0,0 +1,71 @@
+/**
+ * `cloudflare-access` trust mode — Cloudflare Zero Trust / Access
+ * fronting the admin. The platform issues a signed JWT in the
+ * `Cf-Access-Jwt-Assertion` header (or cookie); Gazetta verifies
+ * the signature against Cloudflare's published JWKS and reads the
+ * subject + email from the verified payload.
+ *
+ * # Why JWT verification, not header trust
+ *
+ * Cloudflare Access's JWT carries a real signature. Anyone behind
+ * the Worker boundary can claim a header value, but only Cloudflare's
+ * private key can produce a valid token. Verifying the signature is
+ * the security contract — without it, this trust mode is no safer
+ * than `forwarded-user` without a whitelist.
+ *
+ * # JWKS endpoint shape
+ *
+ * Cloudflare publishes per-team-domain JWKS at:
+ *
+ *     https://{teamDomain}.cloudflareaccess.com/cdn-cgi/access/certs
+ *
+ * Operators set `teamDomain` in `site.config.ts admin.auth`; the
+ * provider builds the URL and uses `jose`'s `createRemoteJWKSet`
+ * for verification + automatic key rotation.
+ *
+ * # Failure modes
+ *
+ *   - JWT missing / expired / signature invalid → `AuthenticationError`
+ *     (middleware → 401)
+ *   - JWKS endpoint unreachable → `AuthenticationError` (fail-CLOSED
+ *     here, NOT fail-open like Universal Provider Requirement #5
+ *     suggests for transport errors — auth is the security boundary;
+ *     a JWKS outage that fails open would let unsigned tokens
+ *     through)
+ *   - `aud` claim mismatch (when configured) → `AuthenticationError`
+ *
+ * # SOLID lenses
+ *
+ *   - SRP: JWT verification only. Source-IP extraction is not this
+ *     provider's concern (Cloudflare's signed assertion IS the trust;
+ *     the source IP would be Cloudflare's edge anyway).
+ *   - DIP: jose's `createRemoteJWKSet` is the verifier dependency;
+ *     test injects a different verifier via the optional
+ *     `jwksFactory` constructor option for unit tests.
+ */
+import { type JWTVerifyGetKey } from 'jose';
+import type { AuthIdentityProvider } from '../provider.js';
+export interface CloudflareAccessConfig {
+    /**
+     * Cloudflare Zero Trust team domain (the part before
+     * `.cloudflareaccess.com`). Required. Example: `'acme'` for
+     * `https://acme.cloudflareaccess.com`.
+     */
+    teamDomain: string;
+    /**
+     * Optional `aud` claim verification. Cloudflare Access tokens
+     * carry an `aud` claim identifying the application; production
+     * deployments SHOULD set this to prevent token replay across
+     * Access-protected apps in the same team domain.
+     */
+    audience?: string;
+    /** Optional default role until Cut 6's role-resolver wires up. */
+    defaultRole?: string;
+    /**
+     * Internal: factory for the JWKS verifier. Tests inject a stub;
+     * production calls `createRemoteJWKSet`.
+     */
+    jwksFactory?: (jwksUrl: URL) => JWTVerifyGetKey;
+}
+export declare function createCloudflareAccessAuthProvider(config: CloudflareAccessConfig): AuthIdentityProvider;
+//# sourceMappingURL=cloudflare-access.d.ts.map

package/dist/auth/providers/cloudflare-access.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cloudflare-access.d.ts","sourceRoot":"","sources":["../../../src/auth/providers/cloudflare-access.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AACH,OAAO,EAAkD,KAAK,eAAe,EAAE,MAAM,MAAM,CAAA;AAE3F,OAAO,KAAK,EAAE,oBAAoB,EAAe,MAAM,gBAAgB,CAAA;AAIvE,MAAM,WAAW,sBAAsB;IACrC;;;;OAIG;IACH,UAAU,EAAE,MAAM,CAAA;IAClB;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,kEAAkE;IAClE,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB;;;OAGG;IACH,WAAW,CAAC,EAAE,CAAC,OAAO,EAAE,GAAG,KAAK,eAAe,CAAA;CAChD;AAgBD,wBAAgB,kCAAkC,CAAC,MAAM,EAAE,sBAAsB,GAAG,oBAAoB,CA6DvG"}

package/dist/auth/providers/cloudflare-access.js

@@ -0,0 +1,120 @@
+/**
+ * `cloudflare-access` trust mode — Cloudflare Zero Trust / Access
+ * fronting the admin. The platform issues a signed JWT in the
+ * `Cf-Access-Jwt-Assertion` header (or cookie); Gazetta verifies
+ * the signature against Cloudflare's published JWKS and reads the
+ * subject + email from the verified payload.
+ *
+ * # Why JWT verification, not header trust
+ *
+ * Cloudflare Access's JWT carries a real signature. Anyone behind
+ * the Worker boundary can claim a header value, but only Cloudflare's
+ * private key can produce a valid token. Verifying the signature is
+ * the security contract — without it, this trust mode is no safer
+ * than `forwarded-user` without a whitelist.
+ *
+ * # JWKS endpoint shape
+ *
+ * Cloudflare publishes per-team-domain JWKS at:
+ *
+ *     https://{teamDomain}.cloudflareaccess.com/cdn-cgi/access/certs
+ *
+ * Operators set `teamDomain` in `site.config.ts admin.auth`; the
+ * provider builds the URL and uses `jose`'s `createRemoteJWKSet`
+ * for verification + automatic key rotation.
+ *
+ * # Failure modes
+ *
+ *   - JWT missing / expired / signature invalid → `AuthenticationError`
+ *     (middleware → 401)
+ *   - JWKS endpoint unreachable → `AuthenticationError` (fail-CLOSED
+ *     here, NOT fail-open like Universal Provider Requirement #5
+ *     suggests for transport errors — auth is the security boundary;
+ *     a JWKS outage that fails open would let unsigned tokens
+ *     through)
+ *   - `aud` claim mismatch (when configured) → `AuthenticationError`
+ *
+ * # SOLID lenses
+ *
+ *   - SRP: JWT verification only. Source-IP extraction is not this
+ *     provider's concern (Cloudflare's signed assertion IS the trust;
+ *     the source IP would be Cloudflare's edge anyway).
+ *   - DIP: jose's `createRemoteJWKSet` is the verifier dependency;
+ *     test injects a different verifier via the optional
+ *     `jwksFactory` constructor option for unit tests.
+ */
+import { jwtVerify, createRemoteJWKSet } from 'jose';
+import { AuthenticationError, AuthConfigurationError } from '../errors.js';
+import { expandRole } from '../capabilities.js';
+export function createCloudflareAccessAuthProvider(config) {
+    if (!config.teamDomain || config.teamDomain.length === 0) {
+        throw new AuthConfigurationError('cloudflare-access trust mode requires teamDomain (your Cloudflare Zero Trust team domain, e.g. "acme")');
+    }
+    // Validate the teamDomain shape — Cloudflare team domains are
+    // lowercase alphanumeric + hyphens; reject obvious typos.
+    if (!/^[a-z0-9][a-z0-9-]*$/.test(config.teamDomain)) {
+        throw new AuthConfigurationError(`Invalid teamDomain "${config.teamDomain}": must be lowercase alphanumeric + hyphens (the part before .cloudflareaccess.com)`);
+    }
+    const jwksUrl = new URL(`https://${config.teamDomain}.cloudflareaccess.com/cdn-cgi/access/certs`);
+    const expectedIssuer = `https://${config.teamDomain}.cloudflareaccess.com`;
+    const jwks = (config.jwksFactory ?? createRemoteJWKSet)(jwksUrl);
+    const defaultRole = config.defaultRole ?? 'editor';
+    return {
+        trustMode: 'cloudflare-access',
+        async extractPrincipal(req) {
+            // Cloudflare Access can deliver the assertion in either a
+            // header or cookie. We accept both; header takes precedence
+            // because it's the documented integration path.
+            const token = req.headers.get('cf-access-jwt-assertion') ?? extractFromCookie(req.headers.get('cookie'));
+            if (!token) {
+                // No Cloudflare-Access token at all — anonymous. Middleware
+                // turns this into 401.
+                return null;
+            }
+            let payload;
+            try {
+                const result = await jwtVerify(token, jwks, {
+                    issuer: expectedIssuer,
+                    audience: config.audience,
+                });
+                payload = result.payload;
+            }
+            catch (err) {
+                // jose throws JOSEError subclasses for signature / expiry /
+                // claim mismatches. We don't differentiate — every failure
+                // surfaces as AuthenticationError → 401 per Universal
+                // Provider Requirement (auth fails closed on token failure).
+                throw new AuthenticationError(`Cloudflare Access JWT verification failed: ${err.message}`);
+            }
+            const id = payload.sub ?? payload.identity_nonce;
+            if (!id) {
+                throw new AuthenticationError('Cloudflare Access JWT has no sub or identity_nonce claim');
+            }
+            return {
+                id,
+                email: payload.email,
+                role: defaultRole,
+                trustMode: 'cloudflare-access',
+                capabilities: expandRole(defaultRole) ?? [],
+            };
+        },
+    };
+}
+/**
+ * Cloudflare Access also delivers the JWT via the
+ * `CF_Authorization` cookie. Extract it from the Cookie header
+ * if present.
+ */
+function extractFromCookie(cookieHeader) {
+    if (!cookieHeader)
+        return null;
+    const cookies = cookieHeader.split(';');
+    for (const cookie of cookies) {
+        const trimmed = cookie.trim();
+        if (trimmed.startsWith('CF_Authorization=')) {
+            return trimmed.slice('CF_Authorization='.length);
+        }
+    }
+    return null;
+}
+//# sourceMappingURL=cloudflare-access.js.map

package/dist/auth/providers/cloudflare-access.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cloudflare-access.js","sourceRoot":"","sources":["../../../src/auth/providers/cloudflare-access.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AACH,OAAO,EAAE,SAAS,EAAE,kBAAkB,EAAyC,MAAM,MAAM,CAAA;AAG3F,OAAO,EAAE,mBAAmB,EAAE,sBAAsB,EAAE,MAAM,cAAc,CAAA;AAC1E,OAAO,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAA;AAuC/C,MAAM,UAAU,kCAAkC,CAAC,MAA8B;IAC/E,IAAI,CAAC,MAAM,CAAC,UAAU,IAAI,MAAM,CAAC,UAAU,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACzD,MAAM,IAAI,sBAAsB,CAC9B,wGAAwG,CACzG,CAAA;IACH,CAAC;IACD,8DAA8D;IAC9D,0DAA0D;IAC1D,IAAI,CAAC,sBAAsB,CAAC,IAAI,CAAC,MAAM,CAAC,UAAU,CAAC,EAAE,CAAC;QACpD,MAAM,IAAI,sBAAsB,CAC9B,uBAAuB,MAAM,CAAC,UAAU,qFAAqF,CAC9H,CAAA;IACH,CAAC;IAED,MAAM,OAAO,GAAG,IAAI,GAAG,CAAC,WAAW,MAAM,CAAC,UAAU,4CAA4C,CAAC,CAAA;IACjG,MAAM,cAAc,GAAG,WAAW,MAAM,CAAC,UAAU,uBAAuB,CAAA;IAC1E,MAAM,IAAI,GAAG,CAAC,MAAM,CAAC,WAAW,IAAI,kBAAkB,CAAC,CAAC,OAAO,CAAC,CAAA;IAChE,MAAM,WAAW,GAAG,MAAM,CAAC,WAAW,IAAI,QAAQ,CAAA;IAElD,OAAO;QACL,SAAS,EAAE,mBAAmB;QAC9B,KAAK,CAAC,gBAAgB,CAAC,GAAgB;YACrC,0DAA0D;YAC1D,4DAA4D;YAC5D,gDAAgD;YAChD,MAAM,KAAK,GAAG,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,yBAAyB,CAAC,IAAI,iBAAiB,CAAC,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC,CAAA;YACxG,IAAI,CAAC,KAAK,EAAE,CAAC;gBACX,4DAA4D;gBAC5D,uBAAuB;gBACvB,OAAO,IAAI,CAAA;YACb,CAAC;YAED,IAAI,OAA+B,CAAA;YACnC,IAAI,CAAC;gBACH,MAAM,MAAM,GAAG,MAAM,SAAS,CAAyB,KAAK,EAAE,IAAI,EAAE;oBAClE,MAAM,EAAE,cAAc;oBACtB,QAAQ,EAAE,MAAM,CAAC,QAAQ;iBAC1B,CAAC,CAAA;gBACF,OAAO,GAAG,MAAM,CAAC,OAAO,CAAA;YAC1B,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACb,4DAA4D;gBAC5D,2DAA2D;gBAC3D,sDAAsD;gBACtD,6DAA6D;gBAC7D,MAAM,IAAI,mBAAmB,CAAC,8CAA+C,GAAa,CAAC,OAAO,EAAE,CAAC,CAAA;YACvG,CAAC;YAED,MAAM,EAAE,GAAG,OAAO,CAAC,GAAG,IAAI,OAAO,CAAC,cAAc,CAAA;YAChD,IAAI,CAAC,EAAE,EAAE,CAAC;gBACR,MAAM,IAAI,mBAAmB,CAAC,0DAA0D,CAAC,CAAA;YAC3F,CAAC;YAED,OAAO;gBACL,EAAE;gBACF,KAAK,EAAE,OAAO,CAAC,KAAK;gBACpB,IAAI,EAAE,WAAW;gBACjB,SAAS,EAAE,mBAAmB;gBAC9B,YAAY,EAAE,UAAU,CAAC,WAAW,CAAC,IAAI,EAAE;aAC5C,CAAA;QACH,CAAC;KACF,CAAA;AACH,CAAC;AAED;;;;GAIG;AACH,SAAS,iBAAiB,CAAC,YAAgC;IACzD,IAAI,CAAC,YAAY;QAAE,OAAO,IAAI,CAAA;IAC9B,MAAM,OAAO,GAAG,YAAY,CAAC,KAAK,CAAC,GAAG,CAAC,CAAA;IACvC,KAAK,MAAM,MAAM,IAAI,OAAO,EAAE,CAAC;QAC7B,MAAM,OAAO,GAAG,MAAM,CAAC,IAAI,EAAE,CAAA;QAC7B,IAAI,OAAO,CAAC,UAAU,CAAC,mBAAmB,CAAC,EAAE,CAAC;YAC5C,OAAO,OAAO,CAAC,KAAK,CAAC,mBAAmB,CAAC,MAAM,CAAC,CAAA;QAClD,CAAC;IACH,CAAC;IACD,OAAO,IAAI,CAAA;AACb,CAAC"}

package/dist/auth/providers/forwarded-user.d.ts

@@ -0,0 +1,31 @@
+import type { AuthIdentityProvider } from '../provider.js';
+export interface ForwardedUserConfig {
+    /**
+     * Whitelisted source IPs / CIDRs that may set the forwarded
+     * headers. Empty (or undefined) when `allowAnyOrigin: true`.
+     * Validated at config-load.
+     */
+    trustedProxies?: readonly string[];
+    /**
+     * Explicit opt-out of source-IP protection. Required when
+     * `trustedProxies` is empty. Use only in dev or trusted private
+     * networks.
+     */
+    allowAnyOrigin?: boolean;
+    /**
+     * Group claim → role mapping from the upstream layer's
+     * `X-Forwarded-Groups` header. Resolver (Cut 6) consumes this;
+     * the provider just exposes the raw groups via Principal.role.
+     * Until Cut 6 lands, the provider returns `role: 'editor'` as a
+     * sensible default — overridden once role-resolver wires up.
+     */
+    defaultRole?: string;
+}
+/**
+ * Construct a `forwarded-user` provider. Validates `trustedProxies`
+ * at construction (per Universal Provider Requirement #6 — config
+ * errors throw; transport errors fail-open). Returned provider is
+ * stateless after construction; safe to share across requests.
+ */
+export declare function createForwardedUserAuthProvider(config: ForwardedUserConfig): AuthIdentityProvider;
+//# sourceMappingURL=forwarded-user.d.ts.map

package/dist/auth/providers/forwarded-user.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"forwarded-user.d.ts","sourceRoot":"","sources":["../../../src/auth/providers/forwarded-user.ts"],"names":[],"mappings":"AAuCA,OAAO,KAAK,EAAE,oBAAoB,EAAe,MAAM,gBAAgB,CAAA;AAKvE,MAAM,WAAW,mBAAmB;IAClC;;;;OAIG;IACH,cAAc,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;IAClC;;;;OAIG;IACH,cAAc,CAAC,EAAE,OAAO,CAAA;IACxB;;;;;;OAMG;IACH,WAAW,CAAC,EAAE,MAAM,CAAA;CACrB;AAED;;;;;GAKG;AACH,wBAAgB,+BAA+B,CAAC,MAAM,EAAE,mBAAmB,GAAG,oBAAoB,CAsEjG"}

package/dist/auth/providers/forwarded-user.js

@@ -0,0 +1,72 @@
+import { AuthenticationError, AuthConfigurationError } from '../errors.js';
+import { ipMatchesAny, parseRules } from '../ip-match.js';
+import { expandRole } from '../capabilities.js';
+/**
+ * Construct a `forwarded-user` provider. Validates `trustedProxies`
+ * at construction (per Universal Provider Requirement #6 — config
+ * errors throw; transport errors fail-open). Returned provider is
+ * stateless after construction; safe to share across requests.
+ */
+export function createForwardedUserAuthProvider(config) {
+    // Pre-parse the trustedProxies list at construction so per-request
+    // checks are O(N) over already-parsed rules. Throws AuthConfigurationError
+    // at boot if any rule is malformed — operator sees the failure
+    // before requests start arriving.
+    let parsedRules = [];
+    if (config.trustedProxies && config.trustedProxies.length > 0) {
+        try {
+            parsedRules = parseRules(config.trustedProxies);
+        }
+        catch (err) {
+            throw new AuthConfigurationError(`Invalid trustedProxies entry: ${err.message}. Each entry must be an IP literal (e.g. "10.0.0.1") or CIDR (e.g. "10.0.0.0/8").`);
+        }
+    }
+    if (!config.allowAnyOrigin && parsedRules.length === 0) {
+        // Schema-level refine should catch this, but defense-in-depth:
+        // if a caller bypasses the schema (e.g., constructed by a plugin
+        // with a wrong shape), surface the error at construction.
+        throw new AuthConfigurationError('forwarded-user trust mode requires trustedProxies (IP whitelist) OR allowAnyOrigin: true');
+    }
+    const defaultRole = config.defaultRole ?? 'editor';
+    return {
+        trustMode: 'forwarded-user',
+        async extractPrincipal(req) {
+            // Source-IP protection FIRST — before any header read. A
+            // request from an untrusted source has its forwarded headers
+            // ignored entirely; we treat it as if the headers weren't
+            // set. Returning null lets the middleware decide between 401
+            // (require auth) and synthetic anonymous (none-mode-style).
+            // For forwarded-user we always require auth — middleware
+            // surfaces this as 401.
+            if (!config.allowAnyOrigin) {
+                if (!req.sourceIp || !ipMatchesAny(req.sourceIp, parsedRules)) {
+                    throw new AuthenticationError(req.sourceIp
+                        ? `Request source IP ${req.sourceIp} is not in the configured trustedProxies whitelist`
+                        : 'Request source IP is unknown; trusted-proxy verification cannot run');
+                }
+            }
+            const user = req.headers.get('x-forwarded-user');
+            if (!user || user.length === 0) {
+                // No identity header — anonymous. Middleware turns this
+                // into 401.
+                return null;
+            }
+            const email = req.headers.get('x-forwarded-email') ?? undefined;
+            // Capabilities = the default role's built-in capability set.
+            // Group-claim → role mapping (via roleMapping config + the
+            // X-Forwarded-Groups header) is a follow-up. For v1 every
+            // authenticated forwarded-user gets the configured defaultRole's
+            // capabilities; operators wanting role-by-group set the
+            // roleMapping in admin.auth and override defaultRole.
+            const capabilities = expandRole(defaultRole) ?? [];
+            return {
+                id: user,
+                email,
+                role: defaultRole,
+                trustMode: 'forwarded-user',
+                capabilities,
+            };
+        },
+    };
+}
+//# sourceMappingURL=forwarded-user.js.map

package/dist/auth/providers/forwarded-user.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"forwarded-user.js","sourceRoot":"","sources":["../../../src/auth/providers/forwarded-user.ts"],"names":[],"mappings":"AAwCA,OAAO,EAAE,mBAAmB,EAAE,sBAAsB,EAAE,MAAM,cAAc,CAAA;AAC1E,OAAO,EAAE,YAAY,EAAmB,UAAU,EAAE,MAAM,gBAAgB,CAAA;AAC1E,OAAO,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAA;AAyB/C;;;;;GAKG;AACH,MAAM,UAAU,+BAA+B,CAAC,MAA2B;IACzE,mEAAmE;IACnE,2EAA2E;IAC3E,+DAA+D;IAC/D,kCAAkC;IAClC,IAAI,WAAW,GAAiB,EAAE,CAAA;IAClC,IAAI,MAAM,CAAC,cAAc,IAAI,MAAM,CAAC,cAAc,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC9D,IAAI,CAAC;YACH,WAAW,GAAG,UAAU,CAAC,MAAM,CAAC,cAAc,CAAC,CAAA;QACjD,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,MAAM,IAAI,sBAAsB,CAC9B,iCAAkC,GAAa,CAAC,OAAO,mFAAmF,CAC3I,CAAA;QACH,CAAC;IACH,CAAC;IACD,IAAI,CAAC,MAAM,CAAC,cAAc,IAAI,WAAW,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACvD,+DAA+D;QAC/D,iEAAiE;QACjE,0DAA0D;QAC1D,MAAM,IAAI,sBAAsB,CAC9B,0FAA0F,CAC3F,CAAA;IACH,CAAC;IAED,MAAM,WAAW,GAAG,MAAM,CAAC,WAAW,IAAI,QAAQ,CAAA;IAElD,OAAO;QACL,SAAS,EAAE,gBAAgB;QAC3B,KAAK,CAAC,gBAAgB,CAAC,GAAgB;YACrC,yDAAyD;YACzD,6DAA6D;YAC7D,0DAA0D;YAC1D,6DAA6D;YAC7D,4DAA4D;YAC5D,yDAAyD;YACzD,wBAAwB;YACxB,IAAI,CAAC,MAAM,CAAC,cAAc,EAAE,CAAC;gBAC3B,IAAI,CAAC,GAAG,CAAC,QAAQ,IAAI,CAAC,YAAY,CAAC,GAAG,CAAC,QAAQ,EAAE,WAAW,CAAC,EAAE,CAAC;oBAC9D,MAAM,IAAI,mBAAmB,CAC3B,GAAG,CAAC,QAAQ;wBACV,CAAC,CAAC,qBAAqB,GAAG,CAAC,QAAQ,oDAAoD;wBACvF,CAAC,CAAC,qEAAqE,CAC1E,CAAA;gBACH,CAAC;YACH,CAAC;YAED,MAAM,IAAI,GAAG,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,kBAAkB,CAAC,CAAA;YAChD,IAAI,CAAC,IAAI,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;gBAC/B,wDAAwD;gBACxD,YAAY;gBACZ,OAAO,IAAI,CAAA;YACb,CAAC;YAED,MAAM,KAAK,GAAG,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,mBAAmB,CAAC,IAAI,SAAS,CAAA;YAC/D,6DAA6D;YAC7D,2DAA2D;YAC3D,0DAA0D;YAC1D,iEAAiE;YACjE,wDAAwD;YACxD,sDAAsD;YACtD,MAAM,YAAY,GAAG,UAAU,CAAC,WAAW,CAAC,IAAI,EAAE,CAAA;YAClD,OAAO;gBACL,EAAE,EAAE,IAAI;gBACR,KAAK;gBACL,IAAI,EAAE,WAAW;gBACjB,SAAS,EAAE,gBAAgB;gBAC3B,YAAY;aACb,CAAA;QACH,CAAC;KACF,CAAA;AACH,CAAC"}

package/dist/auth/providers/none.d.ts

@@ -0,0 +1,6 @@
+import type { AuthIdentityProvider } from '../provider.js';
+/** Reserved subject identifier for unauthenticated / pre-RBAC contexts. */
+export declare const UNKNOWN_ACTOR_ID = "unknown";
+/** Singleton instance — `none` mode has no per-instance state. */
+export declare const noneAuthProvider: AuthIdentityProvider;
+//# sourceMappingURL=none.d.ts.map

package/dist/auth/providers/none.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"none.d.ts","sourceRoot":"","sources":["../../../src/auth/providers/none.ts"],"names":[],"mappings":"AAmCA,OAAO,KAAK,EAAE,oBAAoB,EAAe,MAAM,gBAAgB,CAAA;AAEvE,2EAA2E;AAC3E,eAAO,MAAM,gBAAgB,YAAY,CAAA;AAEzC,kEAAkE;AAClE,eAAO,MAAM,gBAAgB,EAAE,oBAc9B,CAAA"}

package/dist/auth/providers/none.js

@@ -0,0 +1,19 @@
+/** Reserved subject identifier for unauthenticated / pre-RBAC contexts. */
+export const UNKNOWN_ACTOR_ID = 'unknown';
+/** Singleton instance — `none` mode has no per-instance state. */
+export const noneAuthProvider = {
+    trustMode: 'none',
+    async extractPrincipal(_req) {
+        // Always returns the canonical unknown principal with full
+        // capabilities. Never returns null (would force middleware to
+        // synthesize an anonymous principal anyway — cleaner to do it
+        // here once).
+        return {
+            id: UNKNOWN_ACTOR_ID,
+            role: 'admin',
+            trustMode: 'none',
+            capabilities: ['*'],
+        };
+    },
+};
+//# sourceMappingURL=none.js.map

package/dist/auth/providers/none.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"none.js","sourceRoot":"","sources":["../../../src/auth/providers/none.ts"],"names":[],"mappings":"AAqCA,2EAA2E;AAC3E,MAAM,CAAC,MAAM,gBAAgB,GAAG,SAAS,CAAA;AAEzC,kEAAkE;AAClE,MAAM,CAAC,MAAM,gBAAgB,GAAyB;IACpD,SAAS,EAAE,MAAM;IACjB,KAAK,CAAC,gBAAgB,CAAC,IAAiB;QACtC,2DAA2D;QAC3D,8DAA8D;QAC9D,8DAA8D;QAC9D,cAAc;QACd,OAAO;YACL,EAAE,EAAE,gBAAgB;YACpB,IAAI,EAAE,OAAO;YACb,SAAS,EAAE,MAAM;YACjB,YAAY,EAAE,CAAC,GAAG,CAAC;SACpB,CAAA;IACH,CAAC;CACF,CAAA"}

package/dist/auth/providers/tailscale.d.ts

@@ -0,0 +1,7 @@
+import type { AuthIdentityProvider } from '../provider.js';
+export interface TailscaleConfig {
+    /** Optional default role until Cut 6's role-resolver wires up. */
+    defaultRole?: string;
+}
+export declare function createTailscaleAuthProvider(config?: TailscaleConfig): AuthIdentityProvider;
+//# sourceMappingURL=tailscale.d.ts.map

package/dist/auth/providers/tailscale.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tailscale.d.ts","sourceRoot":"","sources":["../../../src/auth/providers/tailscale.ts"],"names":[],"mappings":"AA6BA,OAAO,KAAK,EAAE,oBAAoB,EAAe,MAAM,gBAAgB,CAAA;AAGvE,MAAM,WAAW,eAAe;IAC9B,kEAAkE;IAClE,WAAW,CAAC,EAAE,MAAM,CAAA;CACrB;AAED,wBAAgB,2BAA2B,CAAC,MAAM,GAAE,eAAoB,GAAG,oBAAoB,CA4B9F"}

package/dist/auth/providers/tailscale.js

@@ -0,0 +1,30 @@
+import { expandRole } from '../capabilities.js';
+export function createTailscaleAuthProvider(config = {}) {
+    const defaultRole = config.defaultRole ?? 'editor';
+    return {
+        trustMode: 'tailscale',
+        async extractPrincipal(req) {
+            const login = req.headers.get('tailscale-user-login');
+            if (!login || login.length === 0) {
+                // No tailscale identity — request bypassed Tailscale's
+                // serve. Either the operator misconfigured, or a request
+                // arrived through a different listener. Anonymous → 401.
+                return null;
+            }
+            // Tailscale-User-Login is shaped `user@tailnet.ts.net`.
+            // We treat the whole string as id; operators wanting a
+            // shorter display name can map via roleMapping or use the
+            // tailscale-user-name header if present.
+            return {
+                id: login,
+                // Tailscale's email-shaped login is functionally the user's
+                // email for display purposes.
+                email: login,
+                role: defaultRole,
+                trustMode: 'tailscale',
+                capabilities: expandRole(defaultRole) ?? [],
+            };
+        },
+    };
+}
+//# sourceMappingURL=tailscale.js.map

package/dist/auth/providers/tailscale.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tailscale.js","sourceRoot":"","sources":["../../../src/auth/providers/tailscale.ts"],"names":[],"mappings":"AA8BA,OAAO,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAA;AAO/C,MAAM,UAAU,2BAA2B,CAAC,SAA0B,EAAE;IACtE,MAAM,WAAW,GAAG,MAAM,CAAC,WAAW,IAAI,QAAQ,CAAA;IAClD,OAAO;QACL,SAAS,EAAE,WAAW;QACtB,KAAK,CAAC,gBAAgB,CAAC,GAAgB;YACrC,MAAM,KAAK,GAAG,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,sBAAsB,CAAC,CAAA;YACrD,IAAI,CAAC,KAAK,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;gBACjC,uDAAuD;gBACvD,yDAAyD;gBACzD,yDAAyD;gBACzD,OAAO,IAAI,CAAA;YACb,CAAC;YAED,wDAAwD;YACxD,uDAAuD;YACvD,0DAA0D;YAC1D,yCAAyC;YACzC,OAAO;gBACL,EAAE,EAAE,KAAK;gBACT,4DAA4D;gBAC5D,8BAA8B;gBAC9B,KAAK,EAAE,KAAK;gBACZ,IAAI,EAAE,WAAW;gBACjB,SAAS,EAAE,WAAW;gBACtB,YAAY,EAAE,UAAU,CAAC,WAAW,CAAC,IAAI,EAAE;aAC5C,CAAA;QACH,CAAC;KACF,CAAA;AACH,CAAC"}

package/dist/auth/role-resolver.d.ts

@@ -0,0 +1,38 @@
+import { type RoleMapping } from './types.js';
+export interface ResolveRoleArgs {
+    /** Group names from the upstream auth provider's claim. */
+    groups: ReadonlyArray<string>;
+    /** Operator's roleMapping config (claim + map + defaultRole). */
+    mapping?: RoleMapping;
+    /** Custom role declarations from `site.config.ts admin.auth.roles`. */
+    customRoles?: Readonly<Record<string, ReadonlyArray<string>>>;
+}
+export interface ResolvedRole {
+    /** The chosen Gazetta role name. */
+    name: string;
+    /** The role's capability set after alias expansion. */
+    capabilities: ReadonlyArray<string>;
+}
+/**
+ * Resolve the principal's role + capability set.
+ *
+ * Returns `null` when:
+ *   - No group matches AND `defaultRole` is null (deny access)
+ *   - Resolved role name doesn't expand (unknown role)
+ *
+ * Caller (middleware) translates `null` into 403 / 401 per request
+ * shape.
+ */
+export declare function resolveRole(args: ResolveRoleArgs): ResolvedRole | null;
+/**
+ * Validate that a custom role's capabilities don't redefine
+ * built-in roles with surprising semantics. Per design-auth-rbac.md
+ * Q3: unknown capabilities flagged; reserved built-in role names
+ * cannot be redeclared.
+ *
+ * Returns the list of validation issues; empty array means valid.
+ * Caller decides strict-mode (throw) vs warn-mode (log) per
+ * `admin.auth.strict`.
+ */
+export declare function validateCustomRoles(customRoles: Readonly<Record<string, ReadonlyArray<string>>>): string[];
+//# sourceMappingURL=role-resolver.d.ts.map

package/dist/auth/role-resolver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"role-resolver.d.ts","sourceRoot":"","sources":["../../src/auth/role-resolver.ts"],"names":[],"mappings":"AA8BA,OAAO,EAAkB,KAAK,WAAW,EAAE,MAAM,YAAY,CAAA;AAE7D,MAAM,WAAW,eAAe;IAC9B,2DAA2D;IAC3D,MAAM,EAAE,aAAa,CAAC,MAAM,CAAC,CAAA;IAC7B,iEAAiE;IACjE,OAAO,CAAC,EAAE,WAAW,CAAA;IACrB,uEAAuE;IACvE,WAAW,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC,CAAC,CAAA;CAC9D;AAED,MAAM,WAAW,YAAY;IAC3B,oCAAoC;IACpC,IAAI,EAAE,MAAM,CAAA;IACZ,uDAAuD;IACvD,YAAY,EAAE,aAAa,CAAC,MAAM,CAAC,CAAA;CACpC;AAED;;;;;;;;;GASG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,eAAe,GAAG,YAAY,GAAG,IAAI,CAiCtE;AAED;;;;;;;;;GASG;AACH,wBAAgB,mBAAmB,CAAC,WAAW,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC,CAAC,GAAG,MAAM,EAAE,CAU1G"}

package/dist/auth/role-resolver.js

@@ -0,0 +1,92 @@
+/**
+ * Role resolution — translates upstream group claims into a Gazetta
+ * role + the role's capability set.
+ *
+ * # The resolution chain
+ *
+ *   1. Pull the group list from the principal's claims (header /
+ *      JWT payload — provider-specific, surfaces as a `string[]`)
+ *   2. Walk the operator's `roleMapping.map` from `site.config.ts`;
+ *      first matching upstream group → Gazetta role name
+ *   3. Fall back to `roleMapping.defaultRole` if no group matches;
+ *      `null` means deny access
+ *   4. Expand the role name to its capability set via
+ *      `expandRole(name, customRoles)`
+ *
+ * # Why "first match wins" not "highest precedence"
+ *
+ * Per `design-auth-rbac.md` Q3 lock: priority is array order in the
+ * map config. Operators control precedence by ordering their map.
+ * Predictable, deterministic, no implicit precedence.
+ *
+ * # SOLID lenses
+ *
+ *   - SRP: pure function over (groups, mapping, customRoles);
+ *     doesn't read `site.config.ts` directly, doesn't depend on
+ *     specific provider shape.
+ *   - DIP: providers pass the resolved groups; this module doesn't
+ *     know about JWT claims or HTTP headers.
+ */
+import { expandRole } from './capabilities.js';
+import { BUILT_IN_ROLES } from './types.js';
+/**
+ * Resolve the principal's role + capability set.
+ *
+ * Returns `null` when:
+ *   - No group matches AND `defaultRole` is null (deny access)
+ *   - Resolved role name doesn't expand (unknown role)
+ *
+ * Caller (middleware) translates `null` into 403 / 401 per request
+ * shape.
+ */
+export function resolveRole(args) {
+    const { groups, mapping, customRoles } = args;
+    let roleName;
+    if (mapping) {
+        // First-match-wins per array order. Iteration order of an object
+        // literal is insertion-order in modern JS; operator's config
+        // ordering IS the precedence.
+        for (const [group, role] of Object.entries(mapping.map)) {
+            if (groups.includes(group)) {
+                roleName = role;
+                break;
+            }
+        }
+        // Fall through to defaultRole if no group matched.
+        if (!roleName) {
+            roleName = mapping.defaultRole;
+        }
+    }
+    // Without a mapping (or with an empty map + null defaultRole),
+    // there's no role to assign.
+    if (!roleName)
+        return null;
+    const capabilities = expandRole(roleName, customRoles);
+    if (!capabilities) {
+        // Unknown role — operator misconfiguration. The site-loader
+        // should catch this at boot via strict validation; this is the
+        // defense-in-depth check.
+        return null;
+    }
+    return { name: roleName, capabilities };
+}
+/**
+ * Validate that a custom role's capabilities don't redefine
+ * built-in roles with surprising semantics. Per design-auth-rbac.md
+ * Q3: unknown capabilities flagged; reserved built-in role names
+ * cannot be redeclared.
+ *
+ * Returns the list of validation issues; empty array means valid.
+ * Caller decides strict-mode (throw) vs warn-mode (log) per
+ * `admin.auth.strict`.
+ */
+export function validateCustomRoles(customRoles) {
+    const issues = [];
+    for (const name of Object.keys(customRoles)) {
+        if (name in BUILT_IN_ROLES) {
+            issues.push(`Custom role "${name}" conflicts with a built-in role. Choose a different name; built-in roles can't be redefined.`);
+        }
+    }
+    return issues;
+}
+//# sourceMappingURL=role-resolver.js.map

package/dist/auth/role-resolver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"role-resolver.js","sourceRoot":"","sources":["../../src/auth/role-resolver.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,OAAO,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAA;AAC9C,OAAO,EAAE,cAAc,EAAoB,MAAM,YAAY,CAAA;AAkB7D;;;;;;;;;GASG;AACH,MAAM,UAAU,WAAW,CAAC,IAAqB;IAC/C,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,WAAW,EAAE,GAAG,IAAI,CAAA;IAC7C,IAAI,QAAmC,CAAA;IAEvC,IAAI,OAAO,EAAE,CAAC;QACZ,iEAAiE;QACjE,6DAA6D;QAC7D,8BAA8B;QAC9B,KAAK,MAAM,CAAC,KAAK,EAAE,IAAI,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC;YACxD,IAAI,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC;gBAC3B,QAAQ,GAAG,IAAI,CAAA;gBACf,MAAK;YACP,CAAC;QACH,CAAC;QACD,mDAAmD;QACnD,IAAI,CAAC,QAAQ,EAAE,CAAC;YACd,QAAQ,GAAG,OAAO,CAAC,WAAW,CAAA;QAChC,CAAC;IACH,CAAC;IAED,+DAA+D;IAC/D,6BAA6B;IAC7B,IAAI,CAAC,QAAQ;QAAE,OAAO,IAAI,CAAA;IAE1B,MAAM,YAAY,GAAG,UAAU,CAAC,QAAQ,EAAE,WAAW,CAAC,CAAA;IACtD,IAAI,CAAC,YAAY,EAAE,CAAC;QAClB,4DAA4D;QAC5D,+DAA+D;QAC/D,0BAA0B;QAC1B,OAAO,IAAI,CAAA;IACb,CAAC;IAED,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,YAAY,EAAE,CAAA;AACzC,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,mBAAmB,CAAC,WAA4D;IAC9F,MAAM,MAAM,GAAa,EAAE,CAAA;IAC3B,KAAK,MAAM,IAAI,IAAI,MAAM,CAAC,IAAI,CAAC,WAAW,CAAC,EAAE,CAAC;QAC5C,IAAI,IAAI,IAAI,cAAc,EAAE,CAAC;YAC3B,MAAM,CAAC,IAAI,CACT,gBAAgB,IAAI,+FAA+F,CACpH,CAAA;QACH,CAAC;IACH,CAAC;IACD,OAAO,MAAM,CAAA;AACf,CAAC"}