gazetta 0.6.0 → 0.8.0

package/dist/auth/capabilities.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Test whether a principal's capability set grants the required
+ * capability. Implements wildcard expansion:
+ *
+ *   - `*` (root wildcard) grants everything (including
+ *     wildcard-exempt capabilities — admin role retains the
+ *     escape hatch)
+ *   - `<prefix>:*` grants every capability under that prefix
+ *     EXCEPT capabilities in `WILDCARD_EXEMPT_CAPABILITIES`
+ *   - exact match grants exactly that capability
+ *
+ * Plugin-supplied capabilities use scoped prefixes
+ * (`@my-org/search:rebuild-index`) and follow the same rules:
+ * `@my-org/search:*` grants `@my-org/search:rebuild-index`.
+ */
+export declare function capabilityGrants(granted: ReadonlyArray<string>, required: string): boolean;
+/**
+ * Expand a role name to its capability set. Built-in roles
+ * (`admin`, `editor`, `viewer`) resolve from `BUILT_IN_ROLES`;
+ * custom roles must be supplied via the `customRoles` map at
+ * resolution time (per `design-auth-rbac.md`'s "hybrid built-in
+ * + custom" model).
+ *
+ * Returns null when the role isn't recognized — caller decides
+ * whether to fail-closed (deny access) or fail-open (assign default).
+ */
+export declare function expandRole(roleName: string, customRoles?: Readonly<Record<string, ReadonlyArray<string>>>): ReadonlyArray<string> | null;
+//# sourceMappingURL=capabilities.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"capabilities.d.ts","sourceRoot":"","sources":["../../src/auth/capabilities.ts"],"names":[],"mappings":"AAgDA;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,aAAa,CAAC,MAAM,CAAC,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAe1F;AAED;;;;;;;;;GASG;AACH,wBAAgB,UAAU,CACxB,QAAQ,EAAE,MAAM,EAChB,WAAW,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC,CAAC,GAC5D,aAAa,CAAC,MAAM,CAAC,GAAG,IAAI,CAQ9B"}

package/dist/auth/capabilities.js

@@ -0,0 +1,101 @@
+/**
+ * Capability vocabulary helpers — the closed set of built-in
+ * capabilities and the matching logic for wildcard expansion.
+ *
+ * # Why these helpers live here
+ *
+ * Capabilities are strings, but the matching logic (does
+ * `read:*` grant `read:pages`? does `*` grant everything?) is
+ * load-bearing for every authorization check. Centralizing the
+ * matching logic in pure functions means:
+ *
+ *   - Middleware uses one function, not ad-hoc string compares
+ *   - Tests pin the wildcard semantics in one place
+ *   - Plugin-supplied capabilities (when plugin foundation ships)
+ *     extend via prefix conventions, not by changing matching code
+ *
+ * # SOLID lenses
+ *
+ *   - SRP: matching only; doesn't read configs or extract principals.
+ *   - DIP: middleware depends on this helper, not on the BUILT_IN_ROLES
+ *     constant.
+ */
+import { BUILT_IN_ROLES } from './types.js';
+/**
+ * Privacy-sensitive capabilities that prefix wildcards do NOT
+ * grant. Per design-auth-rbac.md's "Audit-log read access is its
+ * own capability — viewers don't see audit by default", and the
+ * matching design-audit.md note that audit log is its own gate.
+ *
+ * These capabilities require either:
+ *   - explicit grant (the exact capability string in the granted
+ *     list), or
+ *   - root wildcard `*` (admin role)
+ *
+ * Prefix wildcards (`read:*`) DO NOT grant them. Built-in editor
+ * + viewer roles hold `read:*` — they get `read:pages`,
+ * `read:fragments`, `read:assets` but NOT `read:audit-log`.
+ * Operators wanting an "auditor" custom role declare
+ * `['read:*', 'read:audit-log']` explicitly.
+ *
+ * Plugin authors adding privacy-sensitive capabilities extend this
+ * set by exporting their own capability string in this set —
+ * future plugin foundation will likely move this to a registry.
+ * For v1 the set is closed to known built-ins.
+ */
+const WILDCARD_EXEMPT_CAPABILITIES = new Set(['read:audit-log']);
+/**
+ * Test whether a principal's capability set grants the required
+ * capability. Implements wildcard expansion:
+ *
+ *   - `*` (root wildcard) grants everything (including
+ *     wildcard-exempt capabilities — admin role retains the
+ *     escape hatch)
+ *   - `<prefix>:*` grants every capability under that prefix
+ *     EXCEPT capabilities in `WILDCARD_EXEMPT_CAPABILITIES`
+ *   - exact match grants exactly that capability
+ *
+ * Plugin-supplied capabilities use scoped prefixes
+ * (`@my-org/search:rebuild-index`) and follow the same rules:
+ * `@my-org/search:*` grants `@my-org/search:rebuild-index`.
+ */
+export function capabilityGrants(granted, required) {
+    if (required.length === 0)
+        return false;
+    const isExempt = WILDCARD_EXEMPT_CAPABILITIES.has(required);
+    for (const cap of granted) {
+        // Root wildcard always grants — admin retains the escape hatch
+        // even for wildcard-exempt capabilities.
+        if (cap === '*')
+            return true;
+        if (cap === required)
+            return true;
+        // Prefix wildcards skip wildcard-exempt capabilities.
+        if (!isExempt && cap.endsWith(':*')) {
+            const prefix = cap.slice(0, -1); // 'read:*' → 'read:'
+            if (required.startsWith(prefix))
+                return true;
+        }
+    }
+    return false;
+}
+/**
+ * Expand a role name to its capability set. Built-in roles
+ * (`admin`, `editor`, `viewer`) resolve from `BUILT_IN_ROLES`;
+ * custom roles must be supplied via the `customRoles` map at
+ * resolution time (per `design-auth-rbac.md`'s "hybrid built-in
+ * + custom" model).
+ *
+ * Returns null when the role isn't recognized — caller decides
+ * whether to fail-closed (deny access) or fail-open (assign default).
+ */
+export function expandRole(roleName, customRoles) {
+    if (customRoles && roleName in customRoles) {
+        return customRoles[roleName];
+    }
+    if (roleName in BUILT_IN_ROLES) {
+        return BUILT_IN_ROLES[roleName];
+    }
+    return null;
+}
+//# sourceMappingURL=capabilities.js.map

package/dist/auth/capabilities.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"capabilities.js","sourceRoot":"","sources":["../../src/auth/capabilities.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,OAAO,EAAE,cAAc,EAA0B,MAAM,YAAY,CAAA;AAEnE;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,4BAA4B,GAAwB,IAAI,GAAG,CAAC,CAAC,gBAAgB,CAAC,CAAC,CAAA;AAErF;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,gBAAgB,CAAC,OAA8B,EAAE,QAAgB;IAC/E,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,KAAK,CAAA;IACvC,MAAM,QAAQ,GAAG,4BAA4B,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAA;IAC3D,KAAK,MAAM,GAAG,IAAI,OAAO,EAAE,CAAC;QAC1B,+DAA+D;QAC/D,yCAAyC;QACzC,IAAI,GAAG,KAAK,GAAG;YAAE,OAAO,IAAI,CAAA;QAC5B,IAAI,GAAG,KAAK,QAAQ;YAAE,OAAO,IAAI,CAAA;QACjC,sDAAsD;QACtD,IAAI,CAAC,QAAQ,IAAI,GAAG,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;YACpC,MAAM,MAAM,GAAG,GAAG,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAA,CAAC,qBAAqB;YACrD,IAAI,QAAQ,CAAC,UAAU,CAAC,MAAM,CAAC;gBAAE,OAAO,IAAI,CAAA;QAC9C,CAAC;IACH,CAAC;IACD,OAAO,KAAK,CAAA;AACd,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,UAAU,CACxB,QAAgB,EAChB,WAA6D;IAE7D,IAAI,WAAW,IAAI,QAAQ,IAAI,WAAW,EAAE,CAAC;QAC3C,OAAO,WAAW,CAAC,QAAQ,CAAC,CAAA;IAC9B,CAAC;IACD,IAAI,QAAQ,IAAI,cAAc,EAAE,CAAC;QAC/B,OAAO,cAAc,CAAC,QAAQ,CAAqC,CAAA;IACrE,CAAC;IACD,OAAO,IAAI,CAAA;AACb,CAAC"}

package/dist/auth/config.d.ts

@@ -0,0 +1,109 @@
+/**
+ * Zod schema for the `admin.auth` block in `site.config.ts`. This
+ * cut ships only the `none`-mode shape; subsequent cuts add Zod
+ * variants for `forwarded-user`, `cloudflare-access`, etc.
+ *
+ * # Why a discriminated union
+ *
+ * Each trust mode's configuration shape is genuinely different
+ * (`forwarded-user` has `trustedProxyCount`; `cloudflare-access`
+ * has `teamDomain`; `none` has no provider-specific fields). A
+ * discriminated union on `trust:` lets TypeScript narrow per
+ * mode automatically and gives operators IDE autocomplete for the
+ * fields their chosen mode accepts.
+ *
+ * # Defaults
+ *
+ * Operators who don't set `admin.auth` run in `none` mode. The
+ * site-loader treats absent `admin.auth` as `{ trust: 'none' }`.
+ *
+ * # SOLID lenses
+ *
+ *   - SRP: schema validation only; doesn't construct providers.
+ *   - OCP: adding a trust mode appends one variant to the union;
+ *     existing variants unchanged.
+ */
+import { z } from 'zod';
+/**
+ * Top-level discriminated union. All v1 trust modes locked.
+ * Future plugin-supplied modes (per design-auth-rbac.md Q1's plugin
+ * promotion trigger) extend the union via the plugin contract — not
+ * by editing this file.
+ */
+export declare const AuthConfigSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    trust: z.ZodLiteral<"none">;
+    roles: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+        capabilities: z.ZodReadonly<z.ZodArray<z.ZodString>>;
+    }, z.core.$strict>>>;
+    strict: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strict>, z.ZodObject<{
+    trust: z.ZodLiteral<"forwarded-user">;
+    trustedProxies: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    allowAnyOrigin: z.ZodOptional<z.ZodBoolean>;
+    roles: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+        capabilities: z.ZodReadonly<z.ZodArray<z.ZodString>>;
+    }, z.core.$strict>>>;
+    roleMapping: z.ZodOptional<z.ZodObject<{
+        claim: z.ZodString;
+        map: z.ZodRecord<z.ZodString, z.ZodString>;
+        defaultRole: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    }, z.core.$strict>>;
+    strict: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strict>, z.ZodObject<{
+    trust: z.ZodLiteral<"cloudflare-access">;
+    teamDomain: z.ZodString;
+    audience: z.ZodOptional<z.ZodString>;
+    roles: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+        capabilities: z.ZodReadonly<z.ZodArray<z.ZodString>>;
+    }, z.core.$strict>>>;
+    roleMapping: z.ZodOptional<z.ZodObject<{
+        claim: z.ZodString;
+        map: z.ZodRecord<z.ZodString, z.ZodString>;
+        defaultRole: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    }, z.core.$strict>>;
+    strict: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strict>, z.ZodObject<{
+    trust: z.ZodLiteral<"azure-easy-auth">;
+    roles: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+        capabilities: z.ZodReadonly<z.ZodArray<z.ZodString>>;
+    }, z.core.$strict>>>;
+    roleMapping: z.ZodOptional<z.ZodObject<{
+        claim: z.ZodString;
+        map: z.ZodRecord<z.ZodString, z.ZodString>;
+        defaultRole: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    }, z.core.$strict>>;
+    strict: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strict>, z.ZodObject<{
+    trust: z.ZodLiteral<"aws-cognito">;
+    region: z.ZodString;
+    audience: z.ZodOptional<z.ZodString>;
+    roles: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+        capabilities: z.ZodReadonly<z.ZodArray<z.ZodString>>;
+    }, z.core.$strict>>>;
+    roleMapping: z.ZodOptional<z.ZodObject<{
+        claim: z.ZodString;
+        map: z.ZodRecord<z.ZodString, z.ZodString>;
+        defaultRole: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    }, z.core.$strict>>;
+    strict: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strict>, z.ZodObject<{
+    trust: z.ZodLiteral<"tailscale">;
+    roles: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+        capabilities: z.ZodReadonly<z.ZodArray<z.ZodString>>;
+    }, z.core.$strict>>>;
+    roleMapping: z.ZodOptional<z.ZodObject<{
+        claim: z.ZodString;
+        map: z.ZodRecord<z.ZodString, z.ZodString>;
+        defaultRole: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    }, z.core.$strict>>;
+    strict: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strict>], "trust">;
+export type AuthConfig = z.infer<typeof AuthConfigSchema>;
+/**
+ * Reserved-prefix check. Future plugin-supplied capabilities use
+ * plugin-scoped prefixes (e.g., `@my-org/...:`); custom roles MUST
+ * NOT redefine reserved built-in prefixes with conflicting
+ * semantics. The role-resolver enforces this at load time.
+ */
+export declare function isReservedPrefix(capability: string): boolean;
+//# sourceMappingURL=config.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/auth/config.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAkLvB;;;;;GAKG;AACH,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;6BAO3B,CAAA;AAEF,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAA;AAEzD;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAM5D"}

package/dist/auth/config.js

@@ -0,0 +1,221 @@
+/**
+ * Zod schema for the `admin.auth` block in `site.config.ts`. This
+ * cut ships only the `none`-mode shape; subsequent cuts add Zod
+ * variants for `forwarded-user`, `cloudflare-access`, etc.
+ *
+ * # Why a discriminated union
+ *
+ * Each trust mode's configuration shape is genuinely different
+ * (`forwarded-user` has `trustedProxyCount`; `cloudflare-access`
+ * has `teamDomain`; `none` has no provider-specific fields). A
+ * discriminated union on `trust:` lets TypeScript narrow per
+ * mode automatically and gives operators IDE autocomplete for the
+ * fields their chosen mode accepts.
+ *
+ * # Defaults
+ *
+ * Operators who don't set `admin.auth` run in `none` mode. The
+ * site-loader treats absent `admin.auth` as `{ trust: 'none' }`.
+ *
+ * # SOLID lenses
+ *
+ *   - SRP: schema validation only; doesn't construct providers.
+ *   - OCP: adding a trust mode appends one variant to the union;
+ *     existing variants unchanged.
+ */
+import { z } from 'zod';
+import { RESERVED_CAPABILITY_PREFIXES } from './types.js';
+/**
+ * Capability-shape regex. Either a wildcard (`'*'`) or
+ * `<prefix>:<rest>` where `rest` may itself be a wildcard.
+ * Plugin-supplied capabilities use scoped prefixes (e.g.,
+ * `@my-org/search:rebuild-index`); the schema accepts those too.
+ */
+const capabilityRegex = /^(\*|[a-zA-Z@][a-zA-Z0-9@/_-]*:[a-zA-Z*][a-zA-Z0-9_-]*)$/;
+const capabilitySchema = z.string().regex(capabilityRegex, 'Capability must be either "*" or "<prefix>:<rest>"');
+/**
+ * Custom role definition — operator-declared in `site.config.ts`.
+ * Built-in roles (`admin`, `editor`, `viewer`) are predefined and
+ * don't appear here; operators only declare custom roles.
+ */
+const roleSchema = z
+    .object({
+    capabilities: z.array(capabilitySchema).readonly(),
+})
+    .strict();
+const roleMappingSchema = z
+    .object({
+    /** Which JSON claim / header field carries the upstream group list. */
+    claim: z.string(),
+    /** Map from upstream group name to Gazetta role name. */
+    map: z.record(z.string(), z.string()),
+    /** Fallback role when no group matches. `null` denies access. */
+    defaultRole: z.string().nullable().optional(),
+})
+    .strict();
+/**
+ * `none` trust mode — the default. No provider-specific fields.
+ * Operators omitting `admin.auth` entirely fall back to this shape
+ * with all defaults.
+ */
+const noneAuthSchema = z
+    .object({
+    trust: z.literal('none'),
+    /** Custom role declarations (rare in `none` mode but allowed). */
+    roles: z.record(z.string(), roleSchema).optional(),
+    /** Strict mode — invalid roles fail boot vs. log warning. */
+    strict: z.boolean().optional(),
+})
+    .strict();
+/**
+ * `forwarded-user` trust mode — generic reverse-proxy mode. The
+ * upstream layer (oauth2-proxy, Authelia, Caddy with `forward_auth`,
+ * etc.) populates `X-Forwarded-User` and optionally
+ * `X-Forwarded-Email` / `X-Forwarded-Groups`.
+ *
+ * # Header-spoofing protection
+ *
+ * Operators MUST configure source-IP protection per
+ * `design-auth-rbac.md` Q1: either `trustedProxies` (whitelist of
+ * IPs/CIDRs that may set the headers) OR `allowAnyOrigin: true`
+ * (explicit opt-in for dev / private networks).
+ *
+ * Default: fail-closed. Without `trustedProxies` AND without
+ * `allowAnyOrigin`, the provider rejects every request — surfaces
+ * as 401 with a config-hint message. This matches Q4's
+ * "fail-closed" recommendation in the design's "Source-IP whitelist
+ * semantics" open question.
+ */
+const forwardedUserAuthSchema = z
+    .object({
+    trust: z.literal('forwarded-user'),
+    /**
+     * IPs or CIDR blocks that may set the forwarded headers. Each
+     * entry is an IP literal (`192.168.1.10`) or CIDR
+     * (`10.0.0.0/8`, `fd00::/8`). Empty array + missing
+     * `allowAnyOrigin` → all requests rejected.
+     */
+    trustedProxies: z.array(z.string()).optional(),
+    /**
+     * Explicit opt-out of source-IP protection. Use ONLY in dev or
+     * trusted private networks (Tailscale, internal VPNs).
+     * Production deployments behind a public load balancer MUST
+     * use `trustedProxies` instead.
+     */
+    allowAnyOrigin: z.boolean().optional(),
+    roles: z.record(z.string(), roleSchema).optional(),
+    roleMapping: roleMappingSchema.optional(),
+    strict: z.boolean().optional(),
+})
+    .strict()
+    .refine(cfg => cfg.allowAnyOrigin || (cfg.trustedProxies && cfg.trustedProxies.length > 0), {
+    message: 'forwarded-user trust mode requires trustedProxies (IP whitelist) OR allowAnyOrigin: true. Without either, every request is rejected — likely a misconfiguration. Set trustedProxies for production deployments behind a known proxy; set allowAnyOrigin: true only in dev or trusted private networks.',
+    path: ['trustedProxies'],
+});
+/**
+ * `cloudflare-access` trust mode — Cloudflare Zero Trust fronting
+ * the admin. The platform issues a signed JWT in
+ * `Cf-Access-Jwt-Assertion` (or `CF_Authorization` cookie); Gazetta
+ * verifies the signature against Cloudflare's published JWKS.
+ *
+ * # Why no source-IP check
+ *
+ * The signed JWT IS the trust. Source IP would be Cloudflare's edge
+ * regardless of the original client; verifying the signature is the
+ * security boundary.
+ *
+ * # `audience` claim verification
+ *
+ * Optional but strongly recommended. Cloudflare Access tokens carry
+ * an `aud` claim identifying the application; production deployments
+ * SHOULD set this to prevent token replay across other
+ * Access-protected apps in the same team.
+ */
+const cloudflareAccessAuthSchema = z
+    .object({
+    trust: z.literal('cloudflare-access'),
+    /**
+     * Cloudflare Zero Trust team domain (the part before
+     * `.cloudflareaccess.com`). Lowercase alphanumeric + hyphens.
+     */
+    teamDomain: z.string().regex(/^[a-z0-9][a-z0-9-]*$/, 'teamDomain must be lowercase alphanumeric + hyphens'),
+    /** Optional aud claim — recommended for production. */
+    audience: z.string().optional(),
+    roles: z.record(z.string(), roleSchema).optional(),
+    roleMapping: roleMappingSchema.optional(),
+    strict: z.boolean().optional(),
+})
+    .strict();
+/**
+ * `azure-easy-auth` trust mode — Azure App Service Easy Auth.
+ * Trust boundary is the App Service sandbox; Gazetta just decodes
+ * the X-MS-CLIENT-PRINCIPAL header. No provider-specific config
+ * fields — the platform handles auth.
+ */
+const azureEasyAuthSchema = z
+    .object({
+    trust: z.literal('azure-easy-auth'),
+    roles: z.record(z.string(), roleSchema).optional(),
+    roleMapping: roleMappingSchema.optional(),
+    strict: z.boolean().optional(),
+})
+    .strict();
+/**
+ * `aws-cognito` trust mode — AWS ALB + Cognito user pool. JWT
+ * verification against per-region public keys.
+ */
+const awsCognitoAuthSchema = z
+    .object({
+    trust: z.literal('aws-cognito'),
+    /** AWS region (e.g. "us-east-1"). Required for the JWKS URL. */
+    region: z.string().regex(/^[a-z]{2}-[a-z]+-\d+$/, 'region must be an AWS region like "us-east-1"'),
+    /** Optional aud claim — Cognito user-pool app client id. */
+    audience: z.string().optional(),
+    roles: z.record(z.string(), roleSchema).optional(),
+    roleMapping: roleMappingSchema.optional(),
+    strict: z.boolean().optional(),
+})
+    .strict();
+/**
+ * `tailscale` trust mode — Tailscale Funnel / serve. Trust comes
+ * from the tailnet itself (only authenticated members can reach
+ * the listener). No provider-specific config.
+ */
+const tailscaleAuthSchema = z
+    .object({
+    trust: z.literal('tailscale'),
+    roles: z.record(z.string(), roleSchema).optional(),
+    roleMapping: roleMappingSchema.optional(),
+    strict: z.boolean().optional(),
+})
+    .strict();
+/**
+ * Top-level discriminated union. All v1 trust modes locked.
+ * Future plugin-supplied modes (per design-auth-rbac.md Q1's plugin
+ * promotion trigger) extend the union via the plugin contract — not
+ * by editing this file.
+ */
+export const AuthConfigSchema = z.discriminatedUnion('trust', [
+    noneAuthSchema,
+    forwardedUserAuthSchema,
+    cloudflareAccessAuthSchema,
+    azureEasyAuthSchema,
+    awsCognitoAuthSchema,
+    tailscaleAuthSchema,
+]);
+/**
+ * Reserved-prefix check. Future plugin-supplied capabilities use
+ * plugin-scoped prefixes (e.g., `@my-org/...:`); custom roles MUST
+ * NOT redefine reserved built-in prefixes with conflicting
+ * semantics. The role-resolver enforces this at load time.
+ */
+export function isReservedPrefix(capability) {
+    if (capability === '*')
+        return true;
+    const colonIdx = capability.indexOf(':');
+    if (colonIdx <= 0)
+        return false;
+    const prefix = capability.slice(0, colonIdx);
+    return RESERVED_CAPABILITY_PREFIXES.includes(prefix);
+}
+//# sourceMappingURL=config.js.map

package/dist/auth/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../../src/auth/config.ts"],"names":[],"mappings":"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"}

package/dist/auth/errors.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Auth-specific error taxonomy. Distinct from validation errors;
+ * downstream consumers (route handlers, audit recorder) catch these
+ * to map to the right HTTP status and audit outcome.
+ *
+ * # Why a dedicated taxonomy
+ *
+ * Per `design-plugins.md`'s Universal Provider Requirements, every
+ * provider surface has its own error taxonomy. Auth's errors split
+ * along three axes:
+ *
+ *   - Configuration errors (invalid `site.config.ts admin.auth`
+ *     block) — surface at boot, fail closed
+ *   - Authentication errors (the upstream provider couldn't extract
+ *     identity) — surface as 401
+ *   - Authorization errors (principal lacks the required capability)
+ *     — surface as 403
+ *
+ * # SOLID lenses
+ *
+ *   - SRP: error classes own only error identity and HTTP-status
+ *     mapping. They don't carry rendering logic — route handlers
+ *     map to JSON via `error-response.ts`.
+ *   - LSP: every subclass extends `AuthError` so route handlers
+ *     can branch on the base class then narrow by instanceof.
+ */
+/** Base class for all auth-related errors. */
+export declare class AuthError extends Error {
+    readonly name: string;
+    /** HTTP status the route should return. Subclasses override. */
+    readonly httpStatus: number;
+    constructor(message: string);
+}
+/**
+ * Thrown at config-load time when `admin.auth` is malformed (unknown
+ * trust mode, role-mapping references unknown capabilities, etc.).
+ * Admin won't start.
+ */
+export declare class AuthConfigurationError extends AuthError {
+    readonly name = "AuthConfigurationError";
+    readonly httpStatus = 500;
+}
+/**
+ * Thrown when the upstream provider's expected header / claim is
+ * missing, malformed, or fails signature verification. Surfaces as
+ * 401 with `WWW-Authenticate` hint pointing back at the upstream.
+ */
+export declare class AuthenticationError extends AuthError {
+    readonly name = "AuthenticationError";
+    readonly httpStatus = 401;
+}
+/**
+ * Thrown when an authenticated principal lacks the capability the
+ * route requires. Surfaces as 403 with structured body listing
+ * `missing` capabilities and the principal's `role`.
+ */
+export declare class AuthorizationError extends AuthError {
+    readonly name = "AuthorizationError";
+    readonly httpStatus = 403;
+    /**
+     * Capabilities the principal would need to authorize this request.
+     * Surfaced in the 403 body so authenticated users see what they
+     * can't do — per design-auth-rbac.md "Failure mode": existence-
+     * leak risk doesn't justify 404-hide-existence semantics for
+     * already-authenticated users.
+     */
+    readonly missing: ReadonlyArray<string>;
+    /** Principal's role at decision time — surfaced in the 403 body. */
+    readonly role: string;
+    constructor(message: string, missing: ReadonlyArray<string>, role: string);
+}
+//# sourceMappingURL=errors.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/auth/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,8CAA8C;AAC9C,qBAAa,SAAU,SAAQ,KAAK;IAClC,SAAkB,IAAI,EAAE,MAAM,CAAc;IAC5C,gEAAgE;IAChE,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAM;gBACrB,OAAO,EAAE,MAAM;CAG5B;AAED;;;;GAIG;AACH,qBAAa,sBAAuB,SAAQ,SAAS;IACnD,SAAkB,IAAI,4BAA2B;IACjD,SAAkB,UAAU,OAAM;CACnC;AAED;;;;GAIG;AACH,qBAAa,mBAAoB,SAAQ,SAAS;IAChD,SAAkB,IAAI,yBAAwB;IAC9C,SAAkB,UAAU,OAAM;CACnC;AAED;;;;GAIG;AACH,qBAAa,kBAAmB,SAAQ,SAAS;IAC/C,SAAkB,IAAI,wBAAuB;IAC7C,SAAkB,UAAU,OAAM;IAClC;;;;;;OAMG;IACH,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAC,MAAM,CAAC,CAAA;IACvC,oEAAoE;IACpE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;gBACT,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,aAAa,CAAC,MAAM,CAAC,EAAE,IAAI,EAAE,MAAM;CAK1E"}

package/dist/auth/errors.js

@@ -0,0 +1,78 @@
+/**
+ * Auth-specific error taxonomy. Distinct from validation errors;
+ * downstream consumers (route handlers, audit recorder) catch these
+ * to map to the right HTTP status and audit outcome.
+ *
+ * # Why a dedicated taxonomy
+ *
+ * Per `design-plugins.md`'s Universal Provider Requirements, every
+ * provider surface has its own error taxonomy. Auth's errors split
+ * along three axes:
+ *
+ *   - Configuration errors (invalid `site.config.ts admin.auth`
+ *     block) — surface at boot, fail closed
+ *   - Authentication errors (the upstream provider couldn't extract
+ *     identity) — surface as 401
+ *   - Authorization errors (principal lacks the required capability)
+ *     — surface as 403
+ *
+ * # SOLID lenses
+ *
+ *   - SRP: error classes own only error identity and HTTP-status
+ *     mapping. They don't carry rendering logic — route handlers
+ *     map to JSON via `error-response.ts`.
+ *   - LSP: every subclass extends `AuthError` so route handlers
+ *     can branch on the base class then narrow by instanceof.
+ */
+/** Base class for all auth-related errors. */
+export class AuthError extends Error {
+    name = 'AuthError';
+    /** HTTP status the route should return. Subclasses override. */
+    httpStatus = 500;
+    constructor(message) {
+        super(message);
+    }
+}
+/**
+ * Thrown at config-load time when `admin.auth` is malformed (unknown
+ * trust mode, role-mapping references unknown capabilities, etc.).
+ * Admin won't start.
+ */
+export class AuthConfigurationError extends AuthError {
+    name = 'AuthConfigurationError';
+    httpStatus = 500;
+}
+/**
+ * Thrown when the upstream provider's expected header / claim is
+ * missing, malformed, or fails signature verification. Surfaces as
+ * 401 with `WWW-Authenticate` hint pointing back at the upstream.
+ */
+export class AuthenticationError extends AuthError {
+    name = 'AuthenticationError';
+    httpStatus = 401;
+}
+/**
+ * Thrown when an authenticated principal lacks the capability the
+ * route requires. Surfaces as 403 with structured body listing
+ * `missing` capabilities and the principal's `role`.
+ */
+export class AuthorizationError extends AuthError {
+    name = 'AuthorizationError';
+    httpStatus = 403;
+    /**
+     * Capabilities the principal would need to authorize this request.
+     * Surfaced in the 403 body so authenticated users see what they
+     * can't do — per design-auth-rbac.md "Failure mode": existence-
+     * leak risk doesn't justify 404-hide-existence semantics for
+     * already-authenticated users.
+     */
+    missing;
+    /** Principal's role at decision time — surfaced in the 403 body. */
+    role;
+    constructor(message, missing, role) {
+        super(message);
+        this.missing = missing;
+        this.role = role;
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/auth/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/auth/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,8CAA8C;AAC9C,MAAM,OAAO,SAAU,SAAQ,KAAK;IAChB,IAAI,GAAW,WAAW,CAAA;IAC5C,gEAAgE;IACvD,UAAU,GAAW,GAAG,CAAA;IACjC,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAA;IAChB,CAAC;CACF;AAED;;;;GAIG;AACH,MAAM,OAAO,sBAAuB,SAAQ,SAAS;IACjC,IAAI,GAAG,wBAAwB,CAAA;IAC/B,UAAU,GAAG,GAAG,CAAA;CACnC;AAED;;;;GAIG;AACH,MAAM,OAAO,mBAAoB,SAAQ,SAAS;IAC9B,IAAI,GAAG,qBAAqB,CAAA;IAC5B,UAAU,GAAG,GAAG,CAAA;CACnC;AAED;;;;GAIG;AACH,MAAM,OAAO,kBAAmB,SAAQ,SAAS;IAC7B,IAAI,GAAG,oBAAoB,CAAA;IAC3B,UAAU,GAAG,GAAG,CAAA;IAClC;;;;;;OAMG;IACM,OAAO,CAAuB;IACvC,oEAAoE;IAC3D,IAAI,CAAQ;IACrB,YAAY,OAAe,EAAE,OAA8B,EAAE,IAAY;QACvE,KAAK,CAAC,OAAO,CAAC,CAAA;QACd,IAAI,CAAC,OAAO,GAAG,OAAO,CAAA;QACtB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAA;IAClB,CAAC;CACF"}