@karmaniverous/jeeves-server-core 0.4.0 → 0.5.0

package/dist/src/catalog/utilityEntries.d.ts

@@ -0,0 +1,151 @@
+/**
+ * The utility entries of the server catalog: the liveness probe, auth status and magic link, the machine-key exchange routes and search. Pure.
+ *
+ * @packageDocumentation
+ */
+import { z } from 'zod';
+/** The utility entries. */
+export declare const UTILITY_ENTRIES: readonly [{
+    readonly response: z.ZodObject<{
+        ok: z.ZodLiteral<true>;
+    }, z.core.$strip>;
+    readonly auth: "none";
+    readonly kind: "read";
+    readonly name: "health";
+    readonly method: "GET";
+    readonly path: "/health";
+    readonly description: "Liveness check: returns { ok: true }, with no downstream checks.";
+}, {
+    readonly query: z.ZodObject<{
+        exp: z.ZodOptional<z.ZodString>;
+        d: z.ZodOptional<z.ZodString>;
+        dirs: z.ZodOptional<z.ZodString>;
+        s: z.ZodOptional<z.ZodString>;
+        key: z.ZodOptional<z.ZodString>;
+        path: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+    readonly response: z.ZodObject<{
+        authenticated: z.ZodBoolean;
+        email: z.ZodOptional<z.ZodString>;
+        picture: z.ZodOptional<z.ZodString>;
+        isInsider: z.ZodBoolean;
+        keyCreatedAt: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        searchEnabled: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strip>;
+    readonly auth: "none";
+    readonly kind: "read";
+    readonly name: "authStatus";
+    readonly method: "GET";
+    readonly path: "/api/auth/status";
+    readonly description: "Check current authentication status. Returns whether authenticated, email, insider status, and key metadata.";
+}, {
+    readonly body: z.ZodObject<{
+        email: z.ZodOptional<z.ZodString>;
+        returnTo: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+    readonly response: z.ZodObject<{
+        verifyUrl: z.ZodString;
+    }, z.core.$strip>;
+    readonly auth: "none";
+    readonly kind: "write";
+    readonly name: "sendMagicLink";
+    readonly method: "POST";
+    readonly path: "/api/auth/magic";
+    readonly description: "Request a sign-in link by email. Always answers with a verification URL, whether or not the email belongs to an insider.";
+}, {
+    readonly query: z.ZodObject<{
+        path: z.ZodString;
+    }, z.core.$strip>;
+    readonly response: z.ZodObject<{
+        path: z.ZodString;
+        key: z.ZodString;
+    }, z.core.$strip>;
+    readonly auth: {
+        readonly schemes: readonly [{
+            readonly in: "header";
+            readonly name: "X-API-Key";
+        }];
+    };
+    readonly kind: "read";
+    readonly name: "pathKey";
+    readonly method: "GET";
+    readonly path: "/key";
+    readonly description: "Compute the outsider path key for a path from the machine seed sent in X-API-Key.";
+}, {
+    readonly response: z.ZodObject<{
+        key: z.ZodString;
+    }, z.core.$strip>;
+    readonly auth: {
+        readonly schemes: readonly [{
+            readonly in: "header";
+            readonly name: "X-API-Key";
+        }];
+    };
+    readonly kind: "read";
+    readonly name: "insiderKey";
+    readonly method: "GET";
+    readonly path: "/insider-key";
+    readonly description: "Compute the insider key for the machine seed sent in X-API-Key.";
+}, {
+    readonly body: z.ZodObject<{
+        query: z.ZodString;
+        limit: z.ZodOptional<z.ZodNumber>;
+        filter: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    }, z.core.$strip>;
+    readonly response: z.ZodObject<{
+        results: z.ZodArray<z.ZodObject<{
+            filePath: z.ZodString;
+            browsePath: z.ZodString;
+            fileName: z.ZodString;
+            bestScore: z.ZodNumber;
+            domains: z.ZodArray<z.ZodUnknown>;
+            title: z.ZodOptional<z.ZodUnknown>;
+            author: z.ZodOptional<z.ZodUnknown>;
+            participants: z.ZodOptional<z.ZodUnknown>;
+            metadata: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+            chunks: z.ZodArray<z.ZodObject<{
+                text: z.ZodString;
+                index: z.ZodNumber;
+                score: z.ZodNumber;
+            }, z.core.$strip>>;
+            mtime: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>;
+        metadata: z.ZodObject<{
+            domains: z.ZodArray<z.ZodUnknown>;
+            authors: z.ZodArray<z.ZodUnknown>;
+            participants: z.ZodArray<z.ZodUnknown>;
+        }, z.core.$strip>;
+    }, z.core.$strip>;
+    readonly auth: {
+        readonly schemes: readonly [{
+            readonly in: "query";
+            readonly name: "k";
+        }, {
+            readonly in: "cookie";
+            readonly name: "jeeves_session";
+        }];
+        readonly insiderOnly: true;
+    };
+    readonly kind: "read";
+    readonly name: "search";
+    readonly method: "POST";
+    readonly path: "/api/search";
+    readonly description: "Semantic search through jeeves-watcher, grouped by file and filtered to the scopes of the caller.";
+}, {
+    readonly response: z.ZodUnknown;
+    readonly auth: {
+        readonly schemes: readonly [{
+            readonly in: "query";
+            readonly name: "k";
+        }, {
+            readonly in: "cookie";
+            readonly name: "jeeves_session";
+        }];
+        readonly insiderOnly: true;
+    };
+    readonly kind: "read";
+    readonly name: "searchFacets";
+    readonly method: "GET";
+    readonly path: "/api/search/facets";
+    readonly description: "Search facets from jeeves-watcher, passed through unchanged.";
+}];

package/dist/src/catalog/utilityEntries.js

@@ -0,0 +1,62 @@
+import { z } from 'zod';
+import { PUBLIC, MACHINE_SEED, INSIDER_ONLY, route } from './route.js';
+import { healthResponseSchema, authStatusResponseSchema, authStatusQuerySchema, sendMagicLinkResponseSchema, sendMagicLinkBodySchema, pathKeyResponseSchema, insiderKeyResponseSchema, searchResponseSchema, searchBodySchema } from './utilitySchemas.js';
+
+/**
+ * The utility entries of the server catalog: the liveness probe, auth status and magic link, the machine-key exchange routes and search. Pure.
+ *
+ * @packageDocumentation
+ */
+/** The utility entries. */
+const UTILITY_ENTRIES = [
+    {
+        ...route('health', 'GET', '/health'),
+        response: healthResponseSchema,
+        auth: PUBLIC,
+        kind: 'read',
+    },
+    {
+        ...route('authStatus', 'GET', '/api/auth/status'),
+        query: authStatusQuerySchema,
+        response: authStatusResponseSchema,
+        auth: PUBLIC,
+        kind: 'read',
+    },
+    {
+        ...route('sendMagicLink', 'POST', '/api/auth/magic'),
+        body: sendMagicLinkBodySchema,
+        response: sendMagicLinkResponseSchema,
+        auth: PUBLIC,
+        kind: 'write',
+    },
+    {
+        ...route('pathKey', 'GET', '/key'),
+        query: z.object({
+            path: z.string().describe('Path to compute the outsider key for.'),
+        }),
+        response: pathKeyResponseSchema,
+        auth: MACHINE_SEED,
+        kind: 'read',
+    },
+    {
+        ...route('insiderKey', 'GET', '/insider-key'),
+        response: insiderKeyResponseSchema,
+        auth: MACHINE_SEED,
+        kind: 'read',
+    },
+    {
+        ...route('search', 'POST', '/api/search'),
+        body: searchBodySchema,
+        response: searchResponseSchema,
+        auth: INSIDER_ONLY,
+        kind: 'read',
+    },
+    {
+        ...route('searchFacets', 'GET', '/api/search/facets'),
+        response: z.unknown(),
+        auth: INSIDER_ONLY,
+        kind: 'read',
+    },
+];
+
+export { UTILITY_ENTRIES };

package/dist/src/catalog/utilitySchemas.d.ts

@@ -0,0 +1,98 @@
+/**
+ * Request and response schemas of the utility entries: health, auth status, magic link, the key-exchange routes and search, describing what the service's handlers send. Pure.
+ *
+ * @packageDocumentation
+ */
+import { z } from 'zod';
+/** `health` response. */
+export declare const healthResponseSchema: z.ZodObject<{
+    ok: z.ZodLiteral<true>;
+}, z.core.$strip>;
+/**
+ * `authStatus` query: the share parameters (a share credential is resolved
+ * like any other) and the path it is checked against.
+ */
+export declare const authStatusQuerySchema: z.ZodObject<{
+    exp: z.ZodOptional<z.ZodString>;
+    d: z.ZodOptional<z.ZodString>;
+    dirs: z.ZodOptional<z.ZodString>;
+    s: z.ZodOptional<z.ZodString>;
+    key: z.ZodOptional<z.ZodString>;
+    path: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+/** `authStatus` response. */
+export declare const authStatusResponseSchema: z.ZodObject<{
+    authenticated: z.ZodBoolean;
+    email: z.ZodOptional<z.ZodString>;
+    picture: z.ZodOptional<z.ZodString>;
+    isInsider: z.ZodBoolean;
+    keyCreatedAt: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    searchEnabled: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
+/** `sendMagicLink` body. */
+export declare const sendMagicLinkBodySchema: z.ZodObject<{
+    email: z.ZodOptional<z.ZodString>;
+    returnTo: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+/** `sendMagicLink` response. */
+export declare const sendMagicLinkResponseSchema: z.ZodObject<{
+    verifyUrl: z.ZodString;
+}, z.core.$strip>;
+/** `pathKey` response. */
+export declare const pathKeyResponseSchema: z.ZodObject<{
+    path: z.ZodString;
+    key: z.ZodString;
+}, z.core.$strip>;
+/** `insiderKey` response. */
+export declare const insiderKeyResponseSchema: z.ZodObject<{
+    key: z.ZodString;
+}, z.core.$strip>;
+/** `search` body. */
+export declare const searchBodySchema: z.ZodObject<{
+    query: z.ZodString;
+    limit: z.ZodOptional<z.ZodNumber>;
+    filter: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strip>;
+/** One file of the search results, with its matching chunks. */
+export declare const searchResultSchema: z.ZodObject<{
+    filePath: z.ZodString;
+    browsePath: z.ZodString;
+    fileName: z.ZodString;
+    bestScore: z.ZodNumber;
+    domains: z.ZodArray<z.ZodUnknown>;
+    title: z.ZodOptional<z.ZodUnknown>;
+    author: z.ZodOptional<z.ZodUnknown>;
+    participants: z.ZodOptional<z.ZodUnknown>;
+    metadata: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    chunks: z.ZodArray<z.ZodObject<{
+        text: z.ZodString;
+        index: z.ZodNumber;
+        score: z.ZodNumber;
+    }, z.core.$strip>>;
+    mtime: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+/** `search` response. */
+export declare const searchResponseSchema: z.ZodObject<{
+    results: z.ZodArray<z.ZodObject<{
+        filePath: z.ZodString;
+        browsePath: z.ZodString;
+        fileName: z.ZodString;
+        bestScore: z.ZodNumber;
+        domains: z.ZodArray<z.ZodUnknown>;
+        title: z.ZodOptional<z.ZodUnknown>;
+        author: z.ZodOptional<z.ZodUnknown>;
+        participants: z.ZodOptional<z.ZodUnknown>;
+        metadata: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+        chunks: z.ZodArray<z.ZodObject<{
+            text: z.ZodString;
+            index: z.ZodNumber;
+            score: z.ZodNumber;
+        }, z.core.$strip>>;
+        mtime: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    metadata: z.ZodObject<{
+        domains: z.ZodArray<z.ZodUnknown>;
+        authors: z.ZodArray<z.ZodUnknown>;
+        participants: z.ZodArray<z.ZodUnknown>;
+    }, z.core.$strip>;
+}, z.core.$strip>;

package/dist/src/catalog/utilitySchemas.js

@@ -0,0 +1,131 @@
+import { z } from 'zod';
+import { shareQuerySchema } from './route.js';
+
+/**
+ * Request and response schemas of the utility entries: health, auth status, magic link, the key-exchange routes and search, describing what the service's handlers send. Pure.
+ *
+ * @packageDocumentation
+ */
+/** `health` response. */
+const healthResponseSchema = z.object({
+    /** Always true. */
+    ok: z.literal(true),
+});
+/**
+ * `authStatus` query: the share parameters (a share credential is resolved
+ * like any other) and the path it is checked against.
+ */
+const authStatusQuerySchema = shareQuerySchema.extend({
+    /** Path a share credential is verified against (default `/`). */
+    path: z
+        .string()
+        .optional()
+        .describe('Path a share credential is verified against (default /).'),
+});
+/** `authStatus` response. */
+const authStatusResponseSchema = z.object({
+    /** Whether a credential was recognised. */
+    authenticated: z.boolean(),
+    /** Session email, or `key:<name>` for a key. */
+    email: z.string().optional(),
+    /** Profile picture URL of a Google session. */
+    picture: z.string().optional(),
+    /** Whether the caller is an insider. */
+    isInsider: z.boolean(),
+    /** When the insider's key was last rotated (ISO), or null. */
+    keyCreatedAt: z.string().nullable().optional(),
+    /** Sessions only: search is available. */
+    searchEnabled: z.boolean().optional(),
+});
+/** `sendMagicLink` body. */
+const sendMagicLinkBodySchema = z.object({
+    /** Email to send the link to. */
+    email: z.string().optional().describe('Email address to sign in with.'),
+    /** Page to open after sign-in (server-relative). */
+    returnTo: z
+        .string()
+        .optional()
+        .describe('Page to open after sign-in (server-relative).'),
+});
+/** `sendMagicLink` response. */
+const sendMagicLinkResponseSchema = z.object({
+    /** Page where the emailed code is entered (same for every email). */
+    verifyUrl: z.string(),
+});
+/** `pathKey` response. */
+const pathKeyResponseSchema = z.object({
+    /** The path asked for. */
+    path: z.string(),
+    /** Its outsider path key. */
+    key: z.string(),
+});
+/** `insiderKey` response. */
+const insiderKeyResponseSchema = z.object({
+    /** The insider key of the machine seed. */
+    key: z.string(),
+});
+/** `search` body. */
+const searchBodySchema = z.object({
+    /** Search text. */
+    query: z.string().describe('Search text.'),
+    /** Files to return (default 20). */
+    limit: z
+        .number()
+        .int()
+        .positive()
+        .optional()
+        .describe('Files to return (default 20).'),
+    /** Qdrant filter, passed to jeeves-watcher. */
+    filter: z
+        .record(z.string(), z.unknown())
+        .optional()
+        .describe('Qdrant filter, passed to jeeves-watcher.'),
+});
+/** One file of the search results, with its matching chunks. */
+const searchResultSchema = z.object({
+    /** Filesystem path the watcher indexed. */
+    filePath: z.string(),
+    /** Browse path. */
+    browsePath: z.string(),
+    /** File name. */
+    fileName: z.string(),
+    /** Best chunk score. */
+    bestScore: z.number(),
+    /** Domains from the index metadata. */
+    domains: z.array(z.unknown()),
+    /** `title` from the index metadata. */
+    title: z.unknown().optional(),
+    /** `author` from the index metadata. */
+    author: z.unknown().optional(),
+    /** `participants` from the index metadata. */
+    participants: z.unknown().optional(),
+    /** Other index metadata. */
+    metadata: z.record(z.string(), z.unknown()),
+    /** Matching chunks, in document order. */
+    chunks: z.array(z.object({
+        /** Chunk text. */
+        text: z.string(),
+        /** Chunk index. */
+        index: z.number(),
+        /** Chunk score. */
+        score: z.number(),
+    })),
+    /** File modification time (ISO), when readable. */
+    mtime: z.string().optional(),
+});
+/** `search` response. */
+const searchResponseSchema = z.object({
+    /** Files, best first. */
+    results: z.array(searchResultSchema),
+    /** Distinct values across the results, for filter chips. */
+    metadata: z.object({
+        /** Distinct domains. */
+        domains: z.array(z.unknown()),
+        /** Distinct authors. */
+        authors: z.array(z.unknown()),
+        /** Distinct participants. */
+        participants: z.array(z.unknown()),
+    }),
+});
+
+export { authStatusQuerySchema, authStatusResponseSchema, healthResponseSchema, insiderKeyResponseSchema, pathKeyResponseSchema, searchBodySchema, searchResponseSchema, searchResultSchema, sendMagicLinkBodySchema, sendMagicLinkResponseSchema };

package/dist/src/configAuthSchema.d.ts

@@ -0,0 +1,100 @@
+/**
+ * Config schemas for access: auth modes, Google and email login, event
+ * webhooks, access scopes, insiders and keys.
+ *
+ * @packageDocumentation
+ */
+import { z } from 'zod';
+/** Supported authentication methods */
+export declare const authModeSchema: z.ZodEnum<{
+    google: "google";
+    keys: "keys";
+    email: "email";
+}>;
+/** Google OAuth configuration */
+export declare const googleAuthSchema: z.ZodObject<{
+    clientId: z.ZodString;
+    clientSecret: z.ZodString;
+}, z.core.$strip>;
+/** Email (magic link) authentication configuration */
+export declare const emailAuthSchema: z.ZodObject<{
+    smtpUrl: z.ZodString;
+    fromAddress: z.ZodEmail;
+}, z.core.$strip>;
+/** Auth configuration */
+export declare const authSchema: z.ZodObject<{
+    modes: z.ZodArray<z.ZodEnum<{
+        google: "google";
+        keys: "keys";
+        email: "email";
+    }>>;
+    google: z.ZodOptional<z.ZodObject<{
+        clientId: z.ZodString;
+        clientSecret: z.ZodString;
+    }, z.core.$strip>>;
+    sessionSecret: z.ZodOptional<z.ZodString>;
+    email: z.ZodOptional<z.ZodObject<{
+        smtpUrl: z.ZodString;
+        fromAddress: z.ZodEmail;
+    }, z.core.$strip>>;
+    accessContact: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+/** Event webhook configuration */
+export declare const eventConfigSchema: z.ZodObject<{
+    schema: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    cmd: z.ZodString;
+    map: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    timeoutMs: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+/**
+ * Scopes configuration — controls which paths a user/key can access.
+ *
+ * Three forms:
+ * - `string` — single allow pattern (e.g. '/d/*')
+ * - `string[]` — array of allow patterns (shorthand for \{ allow: [...] \})
+ * - `\{ allow?: string[], deny?: string[] \}` — explicit allow/deny rules
+ *
+ * Semantics:
+ * - Path must match at least one allow rule AND NOT match any deny rule
+ * - Omitting `allow` = implicit ['/*'] (allow everything)
+ * - Omitting `deny` = no exclusions
+ * - Omitting scopes entirely = unrestricted access
+ */
+export declare const scopesObjectSchema: z.ZodObject<{
+    allow: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    deny: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>;
+export declare const scopesSchema: z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>, z.ZodObject<{
+    allow: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    deny: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>]>;
+/** Insider entry (identity + scopes + optional persisted seed) */
+export declare const insiderEntrySchema: z.ZodObject<{
+    scopes: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>, z.ZodObject<{
+        allow: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        deny: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strip>]>>;
+    allow: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    deny: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    seed: z.ZodOptional<z.ZodString>;
+    keyCreatedAt: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+/** Key entry — plain string (seed, no scopes) or object with key + optional scopes */
+export declare const keyEntrySchema: z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+    key: z.ZodString;
+    scopes: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>, z.ZodObject<{
+        allow: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        deny: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strip>]>>;
+    allow: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    deny: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>]>;
+/** Check if a string is a named scope identifier (not a path glob). */
+export declare function isScopeName(v: string): boolean;
+/** Helper: collect named scope references from a scopes field value.
+ *
+ * Backward-compat note: `scopes` has historically accepted path globs like "/**" or ["/a","/b"].
+ * We only treat values as *named scope references* if they look like identifiers
+ * (e.g. "restricted", "no-vc") rather than path globs.
+ */
+export declare function getScopeRefs(scopes: unknown): string[];

package/dist/src/configAuthSchema.js

@@ -0,0 +1,119 @@
+import { z } from 'zod';
+
+/**
+ * Config schemas for access: auth modes, Google and email login, event
+ * webhooks, access scopes, insiders and keys.
+ *
+ * @packageDocumentation
+ */
+/** Supported authentication methods */
+const authModeSchema = z.enum(['google', 'keys', 'email']);
+/** Google OAuth configuration */
+const googleAuthSchema = z.object({
+    clientId: z.string().min(1),
+    clientSecret: z.string().min(1),
+});
+/** Email (magic link) authentication configuration */
+const emailAuthSchema = z.object({
+    /** SMTP connection string (e.g. smtps://user:pass\@smtp.example.com:465) */
+    smtpUrl: z.string().min(1),
+    /** Sender email address for magic link emails */
+    fromAddress: z.email(),
+});
+/** Auth configuration */
+const authSchema = z.object({
+    /** Active authentication methods. Order determines priority. */
+    modes: z
+        .array(authModeSchema)
+        .min(1, { message: 'At least one auth mode is required' }),
+    /** Google OAuth config. Required if modes includes "google". */
+    google: googleAuthSchema.optional(),
+    /** Session cookie signing secret. Required if modes includes "google". */
+    sessionSecret: z.string().min(1).optional(),
+    /** Email (magic link) auth config. Required if modes includes "email". */
+    email: emailAuthSchema.optional(),
+    /**
+     * Who to ask for access, shown on the page a refused Google sign-in
+     * gets (#304): free text such as a name and email (an email in it
+     * becomes a `mailto:` link). Without it the page says to ask the
+     * administrator of the server.
+     */
+    accessContact: z.string().trim().min(1).optional(),
+});
+/** Event webhook configuration */
+const eventConfigSchema = z.object({
+    schema: z.record(z.string(), z.unknown()),
+    cmd: z.string(),
+    map: z.record(z.string(), z.unknown()).optional(),
+    timeoutMs: z.number().positive().optional(),
+});
+/**
+ * Scopes configuration — controls which paths a user/key can access.
+ *
+ * Three forms:
+ * - `string` — single allow pattern (e.g. '/d/*')
+ * - `string[]` — array of allow patterns (shorthand for \{ allow: [...] \})
+ * - `\{ allow?: string[], deny?: string[] \}` — explicit allow/deny rules
+ *
+ * Semantics:
+ * - Path must match at least one allow rule AND NOT match any deny rule
+ * - Omitting `allow` = implicit ['/*'] (allow everything)
+ * - Omitting `deny` = no exclusions
+ * - Omitting scopes entirely = unrestricted access
+ */
+const scopesObjectSchema = z.object({
+    allow: z.array(z.string()).optional(),
+    deny: z.array(z.string()).optional(),
+});
+const scopesSchema = z.union([
+    z.string(),
+    z.array(z.string()),
+    scopesObjectSchema,
+]);
+/** Insider entry (identity + scopes + optional persisted seed) */
+const insiderEntrySchema = z.object({
+    scopes: scopesSchema.optional(),
+    /** Extra allow patterns merged on top of named scope references */
+    allow: z.array(z.string()).optional(),
+    /** Extra deny patterns merged on top of named scope references */
+    deny: z.array(z.string()).optional(),
+    /** Auto-generated insider seed, persisted in config.json */
+    seed: z.string().min(1).optional(),
+    /** ISO timestamp of when the seed was created */
+    keyCreatedAt: z.string().optional(),
+});
+/** Key entry — plain string (seed, no scopes) or object with key + optional scopes */
+const keyEntrySchema = z.union([
+    z.string().min(1),
+    z.object({
+        key: z.string().min(1),
+        scopes: scopesSchema.optional(),
+        /** Extra allow patterns merged on top of named scope references */
+        allow: z.array(z.string()).optional(),
+        /** Extra deny patterns merged on top of named scope references */
+        deny: z.array(z.string()).optional(),
+    }),
+]);
+/** Check if a string is a named scope identifier (not a path glob). */
+function isScopeName(v) {
+    return /^[A-Za-z0-9_-]+$/.test(v);
+}
+/** Helper: collect named scope references from a scopes field value.
+ *
+ * Backward-compat note: `scopes` has historically accepted path globs like "/**" or ["/a","/b"].
+ * We only treat values as *named scope references* if they look like identifiers
+ * (e.g. "restricted", "no-vc") rather than path globs.
+ */
+function getScopeRefs(scopes) {
+    if (typeof scopes === 'string')
+        return isScopeName(scopes) ? [scopes] : [];
+    if (Array.isArray(scopes) && scopes.length > 0) {
+        const strs = scopes.filter((v) => typeof v === 'string');
+        if (strs.length !== scopes.length)
+            return [];
+        return strs.filter((v) => isScopeName(v));
+    }
+    return [];
+}
+
+export { authModeSchema, authSchema, emailAuthSchema, eventConfigSchema, getScopeRefs, googleAuthSchema, insiderEntrySchema, isScopeName, keyEntrySchema, scopesObjectSchema, scopesSchema };