canopycms 0.0.67-int.90 → 0.0.67

package/dist/auth/caching-auth-plugin.d.ts

@@ -1,11 +1,7 @@
 import type { AuthPlugin } from './plugin.js';
 import type { UserSearchResult, GroupMetadata, AuthenticationResult } from './types.js';
 import type { CanopyUserId, CanopyGroupId } from '../types.js';
-/**
- * Generic cache provider interface for auth metadata.
- * Any auth system can implement its own cache backend
- * (file-based, Redis, in-memory, etc.)
- */
+/** Auth-metadata cache backend: file-based, Redis, in-memory, whatever. */
 export interface AuthCacheProvider {
     getUser(userId: CanopyUserId): Promise<UserSearchResult | null>;
     getGroup(groupId: CanopyGroupId): Promise<GroupMetadata | null>;
@@ -13,28 +9,21 @@ export interface AuthCacheProvider {
     getAllGroups(): Promise<GroupMetadata[]>;
     getUserExternalGroups(userId: CanopyUserId): Promise<CanopyGroupId[]>;
 }
-/**
- * Token verifier function type.
- * Given a request context, extracts and verifies the auth token,
- * returning the user ID on success.
- */
+/** Extracts and verifies the request's auth token, yielding its user ID. */
 export type TokenVerifier = (context: unknown) => Promise<{
     userId: CanopyUserId;
 } | null>;
 /**
- * Auth plugin that wraps a token verifier with cached metadata lookups.
- *
- * Used in environments where the auth provider API is not reachable
- * (e.g., Lambda with no internet). JWT verification is done locally,
- * and user/group metadata comes from a cache populated externally
- * (e.g., by an EC2 worker).
- *
- * In dev mode, an optional `lazyRefresher` can be provided to auto-populate
- * the cache on first request, eliminating the need to run `worker run-once` manually.
+ * Wraps a token verifier with cached metadata lookups, for environments where
+ * the auth provider's API is unreachable (a Lambda with no internet): JWT
+ * verification happens locally, and user/group metadata comes from a cache
+ * populated externally by the EC2 worker. In dev an optional `lazyRefresher`
+ * populates that cache on first request instead of `worker run-once`.
  *
- * This wrapper only forwards the inner plugin's `verifiesCredentials` affirmation via the
- * `options` constructor param — it cannot launder an insecure plugin, because
- * createNextCanopyContext asserts the INNER plugin (before wrapping) in context-wrapper.ts.
+ * The wrapper only FORWARDS the inner plugin's `verifiesCredentials`
+ * affirmation, via the `options` param. It cannot launder an insecure plugin,
+ * because createNextCanopyContext asserts the INNER plugin before wrapping
+ * (context-wrapper.ts).
  */
 export declare class CachingAuthPlugin implements AuthPlugin {
     private readonly verifyToken;

package/dist/auth/caching-auth-plugin.js

@@ -1,19 +1,16 @@
 import { createDebugLogger } from '../utils/debug.js';
 const log = createDebugLogger({ prefix: 'CachingAuthPlugin' });
 /**
- * Auth plugin that wraps a token verifier with cached metadata lookups.
+ * Wraps a token verifier with cached metadata lookups, for environments where
+ * the auth provider's API is unreachable (a Lambda with no internet): JWT
+ * verification happens locally, and user/group metadata comes from a cache
+ * populated externally by the EC2 worker. In dev an optional `lazyRefresher`
+ * populates that cache on first request instead of `worker run-once`.
  *
- * Used in environments where the auth provider API is not reachable
- * (e.g., Lambda with no internet). JWT verification is done locally,
- * and user/group metadata comes from a cache populated externally
- * (e.g., by an EC2 worker).
- *
- * In dev mode, an optional `lazyRefresher` can be provided to auto-populate
- * the cache on first request, eliminating the need to run `worker run-once` manually.
- *
- * This wrapper only forwards the inner plugin's `verifiesCredentials` affirmation via the
- * `options` constructor param — it cannot launder an insecure plugin, because
- * createNextCanopyContext asserts the INNER plugin (before wrapping) in context-wrapper.ts.
+ * The wrapper only FORWARDS the inner plugin's `verifiesCredentials`
+ * affirmation, via the `options` param. It cannot launder an insecure plugin,
+ * because createNextCanopyContext asserts the INNER plugin before wrapping
+ * (context-wrapper.ts).
  */
 export class CachingAuthPlugin {
     constructor(verifyToken, cache, lazyRefresher, options) {
@@ -26,7 +23,7 @@ export class CachingAuthPlugin {
     async ensureCachePopulated() {
         if (!this.lazyRefresher)
             return;
-        // Use a shared promise so concurrent callers coalesce into a single refresh
+        // A shared promise, so concurrent callers coalesce into one refresh.
         this.refreshPromise ??= this.lazyRefresher()
             .then(() => log.debug('auth', 'Lazy cache refresh completed'))
             .catch((err) => {
@@ -56,7 +53,8 @@ export class CachingAuthPlugin {
             };
         }
         catch {
-            // Cache error — still return authenticated with minimal info
+            // A cache failure must not reject an already-verified token: degrade to
+            // the bare identity, with no external groups.
             log.debug('auth', 'Cache lookup failed, returning minimal user', {
                 userId: identity.userId,
             });

package/dist/auth/context-helpers.d.ts

@@ -1,30 +1,16 @@
 import type { CanopyRequest } from '../http/types.js';
-/**
- * Headers-like interface for auth context.
- * Framework-agnostic - matches Web Headers, Next.js Headers, and any similar interface.
- */
+/** The shape Web Headers, Next.js Headers and anything similar share. */
 export interface HeadersLike {
     get(name: string): string | null;
 }
-/**
- * Type guard to check if context is a CanopyRequest.
- * CanopyRequest has both 'header' method and 'method' property.
- */
+/** A CanopyRequest is recognized by its `header` method plus `method`. */
 export declare function isCanopyRequest(context: unknown): context is CanopyRequest;
-/**
- * Type guard to check if context is a headers-like object.
- * Headers have a 'get' method for retrieving header values.
- */
+/** Headers-like objects are recognized by their `get` method. */
 export declare function isHeadersLike(context: unknown): context is HeadersLike;
 /**
- * Extract headers from various auth context types.
- * Supports CanopyRequest (API routes) and any headers-like object (server components).
- *
- * @returns HeadersLike object or null if context type is unsupported
+ * Headers from either auth context shape -- a CanopyRequest (API routes) or a
+ * headers-like object (server components) -- or null for anything else.
  */
 export declare function extractHeaders(context: unknown): HeadersLike | null;
-/**
- * Validate auth context and throw helpful error if unsupported.
- * Use this in auth plugins to provide clear error messages.
- */
+/** Use this in auth plugins: same as extractHeaders, but throws on null. */
 export declare function validateAuthContext(context: unknown): HeadersLike;

package/dist/auth/context-helpers.js

@@ -1,7 +1,4 @@
-/**
- * Type guard to check if context is a CanopyRequest.
- * CanopyRequest has both 'header' method and 'method' property.
- */
+/** A CanopyRequest is recognized by its `header` method plus `method`. */
 export function isCanopyRequest(context) {
     return (typeof context === 'object' &&
         context !== null &&
@@ -9,10 +6,7 @@ export function isCanopyRequest(context) {
         'method' in context &&
         typeof context.header === 'function');
 }
-/**
- * Type guard to check if context is a headers-like object.
- * Headers have a 'get' method for retrieving header values.
- */
+/** Headers-like objects are recognized by their `get` method. */
 export function isHeadersLike(context) {
     return (typeof context === 'object' &&
         context !== null &&
@@ -20,14 +14,11 @@ export function isHeadersLike(context) {
         typeof context.get === 'function');
 }
 /**
- * Extract headers from various auth context types.
- * Supports CanopyRequest (API routes) and any headers-like object (server components).
- *
- * @returns HeadersLike object or null if context type is unsupported
+ * Headers from either auth context shape -- a CanopyRequest (API routes) or a
+ * headers-like object (server components) -- or null for anything else.
  */
 export function extractHeaders(context) {
     if (isCanopyRequest(context)) {
-        // Wrap CanopyRequest.header() as HeadersLike.get()
         return {
             get: (name) => context.header(name),
         };
@@ -37,10 +28,7 @@ export function extractHeaders(context) {
     }
     return null;
 }
-/**
- * Validate auth context and throw helpful error if unsupported.
- * Use this in auth plugins to provide clear error messages.
- */
+/** Use this in auth plugins: same as extractHeaders, but throws on null. */
 export function validateAuthContext(context) {
     const headers = extractHeaders(context);
     if (!headers) {

package/dist/auth/file-based-auth-cache.d.ts

@@ -2,20 +2,12 @@ import type { AuthCacheProvider } from './caching-auth-plugin.js';
 import type { UserSearchResult, GroupMetadata } from './types.js';
 import type { CanopyUserId, CanopyGroupId } from '../types.js';
 /**
- * File-based auth cache provider.
- * Reads JSON files from a directory that is populated externally
- * (e.g., by an EC2 worker running refreshClerkCache).
+ * Reads a directory populated externally (the EC2 worker's refreshClerkCache)
+ * and holds the result in memory, re-reading whenever a file's mtime changes.
  *
- * Supports two directory layouts:
- * - Snapshot layout: {cachePath}/current/ symlink → snapshot-{ts}/ directory
- * - Flat layout: files directly in {cachePath}/
- *
- * Expects:
- * - users.json   — { users: UserSearchResult[] }
- * - orgs.json    — { groups: GroupMetadata[] }
- * - memberships.json — { memberships: { [userId]: groupId[] } }
- *
- * Caches in memory and re-reads when file mtime changes.
+ * Expects users.json `{ users }`, orgs.json `{ groups }` and memberships.json
+ * `{ memberships: { [userId]: groupId[] } }`, in whichever directory
+ * `resolveActiveCacheDir` picks.
  */
 export declare class FileBasedAuthCache implements AuthCacheProvider {
     private readonly cachePath;
@@ -33,13 +25,10 @@ export declare class FileBasedAuthCache implements AuthCacheProvider {
     private emptyCache;
 }
 /**
- * Write auth cache files atomically using a snapshot directory and symlink swap.
- *
- * 1. Writes files to a timestamped snapshot directory: {cachePath}/snapshot-{ts}/
- * 2. Creates a temporary symlink, then atomically renames it to {cachePath}/current
- * 3. Cleans up old snapshot directories (keeps the 2 most recent)
- *
- * This ensures readers (FileBasedAuthCache) always see a consistent set of files:
- * either the old snapshot or the new one, never a mix.
+ * Write the cache files into a fresh snapshot directory, then swap the `current`
+ * symlink over to it, so a reader always sees one consistent set of files --
+ * the old snapshot or the new one, never a mix. Individual files go down by
+ * temp-file + rename (utils/atomic-write.ts owns that mechanism). The 2 most
+ * recent snapshot directories are kept.
  */
 export declare function writeAuthCacheSnapshot(cachePath: string, files: Record<string, unknown>): Promise<string>;

package/dist/auth/file-based-auth-cache.js

@@ -3,22 +3,16 @@ import path from 'node:path';
 import { createDebugLogger } from '../utils/debug.js';
 const log = createDebugLogger({ prefix: 'FileBasedAuthCache' });
 /**
- * Resolve the active cache directory.
- *
- * Supports two layouts:
- * 1. Snapshot layout (preferred): {cachePath}/current → {cachePath}/snapshot-{ts}/
- *    The `current` symlink points to the active snapshot directory.
- * 2. Flat layout (legacy/simple): files directly in {cachePath}/
- *
- * Returns the directory path where users.json, orgs.json, memberships.json live.
+ * The directory holding users.json, orgs.json and memberships.json: the target
+ * of the `{cachePath}/current` symlink under the preferred snapshot layout, or
+ * `{cachePath}` itself under the flat one.
  */
 async function resolveActiveCacheDir(cachePath) {
     const currentLink = path.join(cachePath, 'current');
     try {
         const target = await fs.readlink(currentLink);
-        // Symlink target may be relative or absolute
         const resolved = path.isAbsolute(target) ? target : path.resolve(cachePath, target);
-        // SECURITY: Validate that resolved target stays within the expected cache directory
+        // SECURITY: the symlink target must stay inside the cache directory.
         const normalizedCache = path.resolve(cachePath);
         const normalizedTarget = path.resolve(resolved);
         if (!normalizedTarget.startsWith(normalizedCache + path.sep) &&
@@ -37,20 +31,12 @@ async function resolveActiveCacheDir(cachePath) {
     }
 }
 /**
- * File-based auth cache provider.
- * Reads JSON files from a directory that is populated externally
- * (e.g., by an EC2 worker running refreshClerkCache).
- *
- * Supports two directory layouts:
- * - Snapshot layout: {cachePath}/current/ symlink → snapshot-{ts}/ directory
- * - Flat layout: files directly in {cachePath}/
+ * Reads a directory populated externally (the EC2 worker's refreshClerkCache)
+ * and holds the result in memory, re-reading whenever a file's mtime changes.
  *
- * Expects:
- * - users.json   — { users: UserSearchResult[] }
- * - orgs.json    — { groups: GroupMetadata[] }
- * - memberships.json — { memberships: { [userId]: groupId[] } }
- *
- * Caches in memory and re-reads when file mtime changes.
+ * Expects users.json `{ users }`, orgs.json `{ groups }` and memberships.json
+ * `{ memberships: { [userId]: groupId[] } }`, in whichever directory
+ * `resolveActiveCacheDir` picks.
  */
 export class FileBasedAuthCache {
     constructor(cachePath) {
@@ -83,7 +69,6 @@ export class FileBasedAuthCache {
         const usersPath = path.join(activeDir, 'users.json');
         const orgsPath = path.join(activeDir, 'orgs.json');
         const membershipsPath = path.join(activeDir, 'memberships.json');
-        // Check max mtime across all three files for cache freshness
         let maxMtime = 0;
         for (const filePath of [usersPath, orgsPath, membershipsPath]) {
             try {
@@ -95,17 +80,14 @@ export class FileBasedAuthCache {
             }
         }
         if (maxMtime === 0) {
-            // No cache files exist — return empty cache
             if (!this.cache) {
                 this.cache = this.emptyCache();
             }
             return this.cache;
         }
-        // If max mtime hasn't changed and we have a cache, return it
         if (this.cache && maxMtime === this.lastMtime) {
             return this.cache;
         }
-        // Load fresh data
         this.cache = await this.loadFromDisk(activeDir);
         this.lastMtime = maxMtime;
         return this.cache;
@@ -168,45 +150,36 @@ export class FileBasedAuthCache {
     }
 }
 /**
- * Write auth cache files atomically using a snapshot directory and symlink swap.
- *
- * 1. Writes files to a timestamped snapshot directory: {cachePath}/snapshot-{ts}/
- * 2. Creates a temporary symlink, then atomically renames it to {cachePath}/current
- * 3. Cleans up old snapshot directories (keeps the 2 most recent)
- *
- * This ensures readers (FileBasedAuthCache) always see a consistent set of files:
- * either the old snapshot or the new one, never a mix.
+ * Write the cache files into a fresh snapshot directory, then swap the `current`
+ * symlink over to it, so a reader always sees one consistent set of files --
+ * the old snapshot or the new one, never a mix. Individual files go down by
+ * temp-file + rename (utils/atomic-write.ts owns that mechanism). The 2 most
+ * recent snapshot directories are kept.
  */
 export async function writeAuthCacheSnapshot(cachePath, files) {
     await fs.mkdir(cachePath, { recursive: true });
     const timestamp = Date.now();
     const snapshotDir = path.join(cachePath, `snapshot-${timestamp}`);
     await fs.mkdir(snapshotDir, { recursive: true });
-    // Write all files to the snapshot directory
     for (const [fileName, data] of Object.entries(files)) {
         const tmpPath = path.join(snapshotDir, `${fileName}.tmp`);
         const finalPath = path.join(snapshotDir, fileName);
         await fs.writeFile(tmpPath, JSON.stringify(data, null, 2), 'utf-8');
         await fs.rename(tmpPath, finalPath);
     }
-    // Atomic symlink swap: create temp symlink, rename over current.
-    //
-    // The target MUST be relative (the bare `snapshot-<ts>` basename), because
-    // writer and reader do not always share a mount namespace. In prod the EC2
-    // worker mounts the EFS filesystem root and writes through
-    // CANOPYCMS_WORKSPACE_ROOT=/mnt/efs/workspace (cachePath
-    // /mnt/efs/workspace/.cache), while the CMS Lambda mounts the /workspace
-    // access point at /mnt/efs and reads the SAME directory as /mnt/efs/.cache.
-    // An absolute target recorded by one is a nonexistent path to the other -
-    // `resolveActiveCacheDir`'s escape guard then correctly rejects it and falls
-    // back to the flat layout, where the worker never writes, leaving the Lambda
-    // with a permanently empty cache. A relative target resolves against
-    // whichever cachePath the reader was given, so it is correct from both.
+    // The symlink target MUST be relative (the bare `snapshot-<ts>` basename),
+    // because writer and reader do not share a mount namespace: in prod the EC2
+    // worker writes through /mnt/efs/workspace/.cache while the CMS Lambda mounts
+    // the /workspace access point and reads the SAME directory as /mnt/efs/.cache.
+    // An absolute target recorded by one is a nonexistent path to the other, and
+    // `resolveActiveCacheDir`'s escape guard then falls back to the flat layout,
+    // where the worker never writes — leaving the Lambda a permanently empty
+    // cache. A relative target resolves against whichever cachePath the reader
+    // was given, so it is correct from both.
     const currentLink = path.join(cachePath, 'current');
     const tmpLink = path.join(cachePath, `current-${timestamp}`);
     await fs.symlink(path.basename(snapshotDir), tmpLink);
     await fs.rename(tmpLink, currentLink);
-    // Clean up old snapshots (keep the 2 most recent)
     await cleanupOldSnapshots(cachePath, 2);
     return snapshotDir;
 }
@@ -222,7 +195,6 @@ async function cleanupOldSnapshots(cachePath, keepCount) {
         .filter((e) => e.startsWith('snapshot-'))
         .sort()
         .reverse();
-    // Skip the most recent `keepCount` snapshots
     for (const snapshot of snapshots.slice(keepCount)) {
         try {
             await fs.rm(path.join(cachePath, snapshot), {

package/dist/auth/plugin.d.ts

@@ -1,98 +1,66 @@
 import type { UserSearchResult, GroupMetadata, AuthenticationResult } from './types.js';
 import type { CanopyUserId, CanopyGroupId } from '../types.js';
 import type { OperatingMode } from '../operating-mode/types.js';
-/**
- * Abstract auth provider interface.
- * Implement this to integrate different auth systems (Clerk, Auth0, NextAuth, etc.)
- */
+/** Implement this to integrate an auth system (Clerk, Auth0, NextAuth, ...). */
 export interface AuthPlugin {
     /**
-     * Affirmative allowlist marker: set to true ONLY on plugins that
-     * cryptographically verify credentials (e.g. Clerk JWT verification).
-     * assertAuthPluginAllowedForMode() rejects any plugin without this marker
-     * whenever the operating mode is 'prod' — absence fails closed, so a
-     * third-party plugin that forgets the marker is rejected, not accepted.
+     * Affirmative allowlist marker: true ONLY on plugins that cryptographically
+     * verify credentials. In 'prod', assertAuthPluginAllowedForMode() rejects any
+     * plugin without it, so a plugin that forgets the marker fails closed.
      */
     readonly verifiesCredentials?: boolean;
     /**
-     * Authenticate user from request context.
-     * Returns user identity (without final groups) - core will apply bootstrap admins.
+     * Authenticate from a request context, returning identity without final
+     * groups; core applies bootstrap admins.
      *
-     * Contract: CREDENTIAL failures (missing/invalid/expired token) resolve to
-     * `{ success: false }` — they map to 401s. CONFIGURATION errors (e.g. a
-     * required secret like CLERK_SECRET_KEY is absent) may THROW instead: they
-     * are operator mistakes, not user mistakes, and should surface as loud 500s
-     * rather than quiet auth denials. Callers invoking authenticate() directly
-     * (custom adapters) should be prepared for a rejection on misconfiguration.
-     *
-     * @param context - Framework-specific context (CanopyRequest, headers, etc.)
-     * @returns AuthenticationResult with user identity or error
+     * CREDENTIAL failures (missing, invalid or expired token) RESOLVE to
+     * `{ success: false }` and map to a 401. CONFIGURATION errors (an absent
+     * CLERK_SECRET_KEY, say) may THROW instead: they are operator mistakes, and
+     * belong in a loud 500 rather than a quiet auth denial. A custom adapter
+     * calling this directly must be ready for that rejection.
      */
     authenticate(context: unknown): Promise<AuthenticationResult>;
-    /**
-     * Search for users (for permission management UI)
-     * @param query - Search string (email, name, etc.)
-     * @param limit - Max results (default 10)
-     */
+    /** For the permission-management UI. */
     searchUsers(query: string, limit?: number): Promise<UserSearchResult[]>;
-    /**
-     * Get detailed user metadata by ID
-     */
     getUserMetadata(userId: CanopyUserId): Promise<UserSearchResult | null>;
-    /**
-     * Get group/organization metadata by ID
-     */
     getGroupMetadata(groupId: CanopyGroupId): Promise<GroupMetadata | null>;
-    /**
-     * List all groups (for permission UI dropdowns)
-     */
+    /** For permission UI dropdowns. */
     listGroups(limit?: number): Promise<GroupMetadata[]>;
-    /**
-     * Search for external groups/organizations (for group management UI)
-     * Optional - only needed if auth provider supports external groups
-     * @param query - Search string (name, ID, etc.)
-     */
+    /** For the group-management UI; only providers with groups need it. */
     searchExternalGroups?(query: string): Promise<Array<{
         id: CanopyGroupId;
         name: string;
     }>>;
     /**
-     * Optional: lightweight token-only verification (no user metadata lookup, no network).
-     * When present, createNextCanopyContext automatically wraps this plugin with
-     * CachingAuthPlugin in prod/dev modes. The cache is populated by the worker daemon.
+     * Token-only verification: no metadata lookup, no network. When present,
+     * createNextCanopyContext wraps this plugin with CachingAuthPlugin in both
+     * modes, over a cache the worker daemon populates.
      */
     verifyTokenOnly?(context: unknown): Promise<{
         userId: CanopyUserId;
     } | null>;
     /**
-     * Optional: create a function that refreshes the auth cache for this plugin.
-     * Used by the worker daemon and CLI run-once to populate the file-based auth cache.
-     * Returns undefined if this plugin doesn't support cache refresh (e.g., missing credentials).
+     * Builds the refresher the worker daemon and CLI run-once use to populate the
+     * file-based auth cache. Undefined when this plugin cannot refresh (no
+     * credentials, say).
      */
     createCacheRefresher?(cachePath: string): (() => Promise<{
         userCount: number;
         groupCount: number;
     }>) | undefined;
 }
-/**
- * Factory function type for creating auth plugins
- */
 export type AuthPluginFactory<TConfig = unknown> = (config: TConfig) => AuthPlugin;
 /**
- * Fail closed: only allow auth plugins that affirmatively declare real
- * credential verification when the CMS runs in production.
- *
- * This is an allowlist, not a denylist: a plugin must set
- * `verifiesCredentials: true` to pass this guard in prod. DevAuthPlugin (and
- * any third-party plugin that forgets to set the marker) trusts request
- * headers/cookies without cryptographic verification, so accepting it with
- * mode 'prod' would let any caller impersonate any user — including admins —
- * by sending a header like `X-Test-User: admin`. Call this wherever an
- * adopter-provided auth plugin meets the operating mode (framework wrappers,
- * request handlers) BEFORE the plugin is wrapped or used.
+ * Fail closed in prod: an ALLOWLIST, so a plugin passes only by setting
+ * `verifiesCredentials: true`. DevAuthPlugin, and any plugin that forgets the
+ * marker, trusts request headers without cryptographic verification, so
+ * accepting one in 'prod' would let any caller impersonate any user, admins
+ * included, with a header like `X-Test-User: admin`. Absence of
+ * `verifyTokenOnly` is NOT a substitute for the marker — the dev plugin
+ * implements that too.
  *
- * Note: checking for the absence of verifyTokenOnly is NOT a substitute for
- * this marker — the dev plugin implements verifyTokenOnly too.
+ * Call this wherever an adopter-provided plugin meets the operating mode
+ * (framework wrappers, request handlers) BEFORE the plugin is wrapped or used.
  *
  * @throws Error when mode is 'prod' and the plugin does not set `verifiesCredentials: true`
  */

package/dist/auth/plugin.js

@@ -1,18 +1,14 @@
 /**
- * Fail closed: only allow auth plugins that affirmatively declare real
- * credential verification when the CMS runs in production.
+ * Fail closed in prod: an ALLOWLIST, so a plugin passes only by setting
+ * `verifiesCredentials: true`. DevAuthPlugin, and any plugin that forgets the
+ * marker, trusts request headers without cryptographic verification, so
+ * accepting one in 'prod' would let any caller impersonate any user, admins
+ * included, with a header like `X-Test-User: admin`. Absence of
+ * `verifyTokenOnly` is NOT a substitute for the marker — the dev plugin
+ * implements that too.
  *
- * This is an allowlist, not a denylist: a plugin must set
- * `verifiesCredentials: true` to pass this guard in prod. DevAuthPlugin (and
- * any third-party plugin that forgets to set the marker) trusts request
- * headers/cookies without cryptographic verification, so accepting it with
- * mode 'prod' would let any caller impersonate any user — including admins —
- * by sending a header like `X-Test-User: admin`. Call this wherever an
- * adopter-provided auth plugin meets the operating mode (framework wrappers,
- * request handlers) BEFORE the plugin is wrapped or used.
- *
- * Note: checking for the absence of verifyTokenOnly is NOT a substitute for
- * this marker — the dev plugin implements verifyTokenOnly too.
+ * Call this wherever an adopter-provided plugin meets the operating mode
+ * (framework wrappers, request handlers) BEFORE the plugin is wrapped or used.
  *
  * @throws Error when mode is 'prod' and the plugin does not set `verifiesCredentials: true`
  */

package/dist/auth/types.d.ts

@@ -1,16 +1,12 @@
 import type { CanopyUserId, CanopyGroupId } from '../types.js';
-/**
- * User search result for permission UI
- */
+/** A user offered as a permission target. */
 export interface UserSearchResult {
     id: CanopyUserId;
     name: string;
     email: string;
     avatarUrl?: string;
 }
-/**
- * Group metadata for permission UI
- */
+/** Group metadata for the permission UI. */
 export interface GroupMetadata {
     id: CanopyGroupId;
     name: string;
@@ -22,12 +18,11 @@ export interface GroupMetadata {
  * ('external'), Canopy's own groups.json ('internal'), or BOTH -- the same ID
  * exists in each universe.
  *
- * 'both' matters for what a grant actually does. The two ID spaces are not
- * namespaced against each other, and `checkPathPermission` matches one
- * flattened `user.groups` list by ID, so granting a colliding ID reaches the
- * internal group's members AND every provider user whose external groups
- * include that ID. Labeling such an option merely 'internal' would understate
- * its blast radius to the admin making the grant.
+ * 'both' changes what a grant does. The two ID spaces are not namespaced against
+ * each other and `checkPathPermission` matches one flattened `user.groups` list
+ * by ID, so granting a colliding ID reaches the internal group's members AND
+ * every provider user carrying that ID externally. Labeling such an option
+ * merely 'internal' would understate that blast radius to the granting admin.
  */
 export type GroupSource = 'internal' | 'external' | 'both';
 /**
@@ -35,21 +30,17 @@ export type GroupSource = 'internal' | 'external' | 'both';
  *
  * Both universes are valid `allowedGroups` values -- `authResultToCanopyUser`
  * (user.ts) flattens external and internal groups into one `user.groups` list
- * and `checkPathPermission` matches `allowedGroups` against it by ID -- so the
- * picker has to offer both. The two ID spaces are not namespaced against each
- * other, hence `source` to disambiguate them in the UI.
+ * that `checkPathPermission` matches by ID -- so the picker offers both, with
+ * `source` disambiguating the two un-namespaced ID spaces in the UI.
  *
  * Internal options deliberately carry no `memberCount`: member identities and
  * counts stay behind the admin-only `groups.getInternal`, while this endpoint
- * is `privileged` (admin or reviewer).
+ * only needs the `privileged` guard (authorization/helpers.ts's `isPrivileged`).
  */
 export interface PermissionGroupOption extends GroupMetadata {
     source: GroupSource;
 }
-/**
- * Authentication result from auth plugins.
- * Returns user identity (without final groups) on success.
- */
+/** An auth plugin's verdict: on success, user identity without final groups. */
 export interface AuthenticationResult {
     success: boolean;
     user?: {