gazetta 0.7.0 → 0.8.0

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":"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"}

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"}

package/dist/auth/types.d.ts

@@ -0,0 +1,150 @@
+/**
+ * Auth + RBAC types — the load-bearing primitives every downstream
+ * foundation (audit, hooks, review-workflow) consumes.
+ *
+ * # Why these types live here
+ *
+ * Gazetta does NOT do authentication itself. Operators put admin
+ * behind upstream auth (Cloudflare Access, oauth2-proxy, Tailscale,
+ * etc.) and Gazetta reads identity from configured request headers.
+ * This module defines the shape of that identity AFTER the upstream
+ * layer has authenticated — what audit records, what hooks see, what
+ * the capability middleware checks.
+ *
+ * # Trust modes
+ *
+ * Each `TrustMode` corresponds to a documented upstream platform.
+ * The auth provider for that mode knows how to extract identity from
+ * that platform's request shape (signed JWT, custom header, etc.).
+ *
+ * # Single role per principal
+ *
+ * Per `design-auth-rbac.md` Q2 lock. Multi-role complexity (precedence
+ * conflicts, role intersection) deferred until concrete operator
+ * demand. Operators who need multi-role today compose custom roles
+ * with the union of needed capabilities.
+ *
+ * # SOLID lenses
+ *
+ *   - SRP: this module owns the type vocabulary; doesn't read or
+ *     write storage; pure data shapes.
+ *   - DIP: downstream consumers (audit, hooks, middleware) depend on
+ *     `Principal` interface, not on which trust mode produced it.
+ *   - ISP: trust modes are a closed enum, not a capability interface
+ *     each provider must implement methods for.
+ */
+/**
+ * The closed set of trust modes Gazetta knows how to extract identity
+ * from. Adding a new mode requires:
+ *   1. New entry in this enum
+ *   2. New `AuthIdentityProvider` implementation under `auth/providers/`
+ *   3. Registration in the trust-mode dispatcher
+ *
+ * Plugin promotion (per design-auth-rbac.md Q1): 3+ operator requests
+ * for an unlisted platform within 6 months → either add in-tree (if
+ * mainstream) OR promote to plugin extension surface.
+ */
+export type TrustMode = 
+/** Default. No upstream auth assumed. Single-author behavior. */
+'none'
+/** Generic reverse-proxy mode (Caddy, oauth2-proxy, Authelia). */
+ | 'forwarded-user'
+/** Cloudflare Access — signed JWT in `Cf-Access-Jwt-Assertion`. */
+ | 'cloudflare-access'
+/** Azure App Service Easy Auth — base64 `X-MS-CLIENT-PRINCIPAL`. */
+ | 'azure-easy-auth'
+/** AWS ALB + Cognito — JWT in `x-amzn-oidc-data`. */
+ | 'aws-cognito'
+/** Tailscale Funnel / serve — `Tailscale-User-Login` header. */
+ | 'tailscale';
+/**
+ * Snapshot of the authenticated user as it reaches Gazetta handlers.
+ * Per `design-auth-rbac.md`'s "Actor is a snapshot, not a live
+ * reference" invariant: subsequent role changes don't rewrite
+ * recorded events.
+ */
+export interface Principal {
+    /**
+     * Stable upstream subject identifier. OIDC `sub`, OAuth subject,
+     * Cloudflare Access `identity_nonce`, etc. NOT email — email
+     * rotates; sub is stable. `'unknown'` for `none` trust mode and
+     * pre-RBAC revisions read post-migration.
+     */
+    id: string;
+    /**
+     * Optional human-readable identifier. Surfaces in audit drawer +
+     * activity feed. Only present when the auth provider exposes it;
+     * pseudonymization (per `design-audit.md`) drops it.
+     */
+    email?: string;
+    /**
+     * Resolved Gazetta role at decision time. Snapshot, not live —
+     * recorded events preserve the role active when the action ran.
+     */
+    role: string;
+    /**
+     * Trust mode that produced this principal. Audit records this so
+     * forensic queries can scope by trust mode (e.g., "all events
+     * where trust=tailscale").
+     */
+    trustMode: TrustMode;
+    /**
+     * Effective capabilities — the role's capability set after alias
+     * expansion. Computed once per request; downstream middleware
+     * reads this directly without re-resolving the role.
+     */
+    capabilities: ReadonlyArray<string>;
+}
+/**
+ * Configured role definition — either built-in (alias of capability
+ * set) or custom (operator-declared in `site.config.ts`'s
+ * `admin.auth.roles` block).
+ */
+export interface Role {
+    /** Role name. Used in `roleMapping` and audit. */
+    name: string;
+    /**
+     * Capabilities granted by this role. Wildcards allowed
+     * (`'read:*'`, `'*'`). Capability validation runs at config-load
+     * (per Q3 lock — unknown capabilities flagged).
+     */
+    capabilities: ReadonlyArray<string>;
+}
+/**
+ * Group-claim → role mapping. Configured per-site; consumed by the
+ * resolver after the auth provider extracts the upstream group list.
+ */
+export interface RoleMapping {
+    /**
+     * Which JSON claim / header field on the upstream principal carries
+     * the group list. Convention: `groups` for OIDC; varies per provider.
+     */
+    claim: string;
+    /** Map from upstream group name to Gazetta role name. */
+    map: Readonly<Record<string, string>>;
+    /**
+     * Fallback when no group matches. `null` means deny access (401);
+     * a role name means assign that role.
+     */
+    defaultRole?: string | null;
+}
+/**
+ * Reserved capability prefixes — first segment of a capability name
+ * (`read:pages` → `read`). Plugin-supplied capabilities use plugin-
+ * scoped prefixes (e.g., `@my-org/search:rebuild-index`).
+ */
+export declare const RESERVED_CAPABILITY_PREFIXES: readonly ["read", "edit", "delete", "publish", "configure", "review", "restore"];
+/**
+ * Capability vocabulary — the closed set of built-in capabilities
+ * that Gazetta routes gate on. Plugin-contributed capabilities
+ * (when plugin foundation ships) extend via plugin-scoped prefixes
+ * — they don't overlap this list.
+ */
+export type BuiltInCapability = 'read:pages' | 'read:fragments' | 'read:assets' | 'read:audit-log' | 'edit:pages' | 'edit:fragments' | 'edit:assets' | 'edit:locale-variants' | 'delete:pages' | 'delete:fragments' | 'delete:assets' | 'publish:non-production' | 'publish:production' | 'configure:site' | 'configure:targets' | 'restore:history' | 'read:*' | 'edit:*' | 'delete:*' | 'publish:*' | '*';
+/**
+ * Built-in role aliases — predefined as capability sets. Custom
+ * roles in `site.config.ts admin.auth.roles` declare capabilities
+ * directly.
+ */
+export declare const BUILT_IN_ROLES: Readonly<Record<string, ReadonlyArray<BuiltInCapability>>>;
+//# sourceMappingURL=types.d.ts.map

package/dist/auth/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/auth/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAEH;;;;;;;;;;GAUG;AACH,MAAM,MAAM,SAAS;AACnB,iEAAiE;AAC/D,MAAM;AACR,kEAAkE;GAChE,gBAAgB;AAClB,mEAAmE;GACjE,mBAAmB;AACrB,oEAAoE;GAClE,iBAAiB;AACnB,qDAAqD;GACnD,aAAa;AACf,gEAAgE;GAC9D,WAAW,CAAA;AAEf;;;;;GAKG;AACH,MAAM,WAAW,SAAS;IACxB;;;;;OAKG;IACH,EAAE,EAAE,MAAM,CAAA;IACV;;;;OAIG;IACH,KAAK,CAAC,EAAE,MAAM,CAAA;IACd;;;OAGG;IACH,IAAI,EAAE,MAAM,CAAA;IACZ;;;;OAIG;IACH,SAAS,EAAE,SAAS,CAAA;IACpB;;;;OAIG;IACH,YAAY,EAAE,aAAa,CAAC,MAAM,CAAC,CAAA;CACpC;AAED;;;;GAIG;AACH,MAAM,WAAW,IAAI;IACnB,kDAAkD;IAClD,IAAI,EAAE,MAAM,CAAA;IACZ;;;;OAIG;IACH,YAAY,EAAE,aAAa,CAAC,MAAM,CAAC,CAAA;CACpC;AAED;;;GAGG;AACH,MAAM,WAAW,WAAW;IAC1B;;;OAGG;IACH,KAAK,EAAE,MAAM,CAAA;IACb,yDAAyD;IACzD,GAAG,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAA;IACrC;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;CAC5B;AAED;;;;GAIG;AACH,eAAO,MAAM,4BAA4B,kFAQ/B,CAAA;AAEV;;;;;GAKG;AACH,MAAM,MAAM,iBAAiB,GAEzB,YAAY,GACZ,gBAAgB,GAChB,aAAa,GACb,gBAAgB,GAEhB,YAAY,GACZ,gBAAgB,GAChB,aAAa,GACb,sBAAsB,GAEtB,cAAc,GACd,kBAAkB,GAClB,eAAe,GAEf,wBAAwB,GACxB,oBAAoB,GAEpB,gBAAgB,GAChB,mBAAmB,GAEnB,iBAAiB,GAEjB,QAAQ,GACR,QAAQ,GACR,UAAU,GACV,WAAW,GACX,GAAG,CAAA;AAEP;;;;GAIG;AACH,eAAO,MAAM,cAAc,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,iBAAiB,CAAC,CAAC,CAIrF,CAAA"}