@karmaniverous/jeeves-server-core 0.3.0 → 0.5.0

package/dist/src/catalog/fileMutateSchema.js

@@ -0,0 +1,77 @@
+import { z } from 'zod';
+
+/**
+ * The `fileMutate` request body: one object with an `action` enum and the union of the actions' fields, each action's required fields checked by a refinement (catalog bodies must be Zod objects). Pure.
+ *
+ * @packageDocumentation
+ */
+/** The mutation actions. */
+const FILE_MUTATION_ACTIONS = [
+    'edit-block',
+    'delete-block',
+    'insert-block',
+    'edit-cell',
+    'toggle-checkbox',
+];
+/** Fields each action requires. */
+const FILE_MUTATION_REQUIRED_FIELDS = {
+    'edit-block': ['startLine', 'endLine', 'content'],
+    'delete-block': ['startLine', 'endLine'],
+    'insert-block': ['atLine', 'position', 'content'],
+    'edit-cell': ['line', 'col', 'content'],
+    'toggle-checkbox': ['index', 'checked'],
+};
+/** A whole line number (1-based) or index. */
+const whole = (description) => z.number().int().optional().describe(description);
+/** `fileMutate` body. */
+const fileMutateBodySchema = z
+    .object({
+    /** Mutation to perform. */
+    action: z
+        .enum(FILE_MUTATION_ACTIONS)
+        .describe('Mutation action to perform'),
+    /** First line of the block (edit-block, delete-block). */
+    startLine: whole('Start line (1-based) for edit-block/delete-block'),
+    /** Last line of the block (edit-block, delete-block). */
+    endLine: whole('End line (1-based) for edit-block/delete-block'),
+    /** New text (edit-block, insert-block, edit-cell). */
+    content: z
+        .string()
+        .optional()
+        .describe('Content for edit-block, insert-block, or edit-cell'),
+    /** Target line (insert-block). */
+    atLine: whole('Target line (1-based) for insert-block'),
+    /** Insert before or after `atLine` (insert-block). */
+    position: z
+        .enum(['before', 'after'])
+        .optional()
+        .describe('Insert position for insert-block'),
+    /** Insert context (insert-block): `table-row` adds no blank lines. */
+    context: z
+        .string()
+        .optional()
+        .describe('Optional context for insert-block (e.g. "table-row")'),
+    /** Table line (edit-cell). */
+    line: whole('Line number (1-based) for edit-cell'),
+    /** Table column (edit-cell). */
+    col: whole('Column index (0-based) for edit-cell'),
+    /** Checkbox index (toggle-checkbox). */
+    index: whole('Checkbox index (0-based) for toggle-checkbox'),
+    /** Desired state (toggle-checkbox). */
+    checked: z
+        .boolean()
+        .optional()
+        .describe('Desired checked state for toggle-checkbox'),
+})
+    .superRefine((body, ctx) => {
+    for (const field of FILE_MUTATION_REQUIRED_FIELDS[body.action]) {
+        if (body[field] === undefined)
+            ctx.addIssue({
+                code: 'custom',
+                path: [field],
+                message: `${body.action} requires ${field}`,
+            });
+    }
+});
+
+export { FILE_MUTATION_ACTIONS, FILE_MUTATION_REQUIRED_FIELDS, fileMutateBodySchema };

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

@@ -0,0 +1,15 @@
+/**
+ * Browser-safe entry point of jeeves-server-core (`@karmaniverous/jeeves-server-core/catalog`): the endpoint catalog, its request and response schemas and the error codes. Imports only `zod` and `@karmaniverous/jeeves/catalog`, never Node built-ins, so the SDK and the web client can bundle it.
+ *
+ * @packageDocumentation
+ */
+export { SERVER_ERROR_CODES, SERVER_ERROR_STATUS, type ServerErrorCode, } from '../errors.js';
+export { breadcrumbSchema, browseResponseSchema, directoryEntrySchema, directoryListingSchema, driveSchema, drivesResponseSchema, exportCacheClearResponseSchema, exportLinkSchema, fileContentQuerySchema, fileContentResponseSchema, fileMetadataSchema, fileWriteBodySchema, fileWriteResponseSchema, headingSchema, linkInfoResponseSchema, okResponseSchema, } from './contentSchemas.js';
+export { eventLogEntrySchema, receiveEventResponseSchema, } from './eventEntries.js';
+export { FILE_MUTATION_ACTIONS, FILE_MUTATION_REQUIRED_FIELDS, type FileMutateBody, fileMutateBodySchema, } from './fileMutateSchema.js';
+export { oauthCredentialQuerySchema, oauthStartBodySchema, oauthStartResponseSchema, oauthStatusResponseSchema, oauthTokenResponseSchema, } from './oauthEntries.js';
+export { shareQuerySchema } from './route.js';
+export { SERVER_CATALOG, type ServerCatalog, type ServerEntry, type ServerEntryName, type ServerHealth, type ServerInput, type ServerResponse, } from './serverCatalog.js';
+export { linkResponseSchema, resolvePathResponseSchema, rotateKeyResponseSchema, shareBodySchema, shareForBodySchema, shareForResponseSchema, shareResponseSchema, } from './sharingEntries.js';
+export { eventQueueHealthSchema, serverHealthSchema, serviceProbeSchema, } from './statusSchemas.js';
+export { authStatusQuerySchema, authStatusResponseSchema, healthResponseSchema, insiderKeyResponseSchema, pathKeyResponseSchema, searchBodySchema, searchResponseSchema, searchResultSchema, sendMagicLinkBodySchema, sendMagicLinkResponseSchema, } from './utilitySchemas.js';

package/dist/src/catalog/index.js

@@ -0,0 +1,10 @@
+export { SERVER_ERROR_CODES, SERVER_ERROR_STATUS } from '../errors.js';
+export { breadcrumbSchema, browseResponseSchema, directoryEntrySchema, directoryListingSchema, driveSchema, drivesResponseSchema, exportCacheClearResponseSchema, exportLinkSchema, fileContentQuerySchema, fileContentResponseSchema, fileMetadataSchema, fileWriteBodySchema, fileWriteResponseSchema, headingSchema, linkInfoResponseSchema, okResponseSchema } from './contentSchemas.js';
+export { eventLogEntrySchema, receiveEventResponseSchema } from './eventEntries.js';
+export { FILE_MUTATION_ACTIONS, FILE_MUTATION_REQUIRED_FIELDS, fileMutateBodySchema } from './fileMutateSchema.js';
+export { oauthCredentialQuerySchema, oauthStartBodySchema, oauthStartResponseSchema, oauthStatusResponseSchema, oauthTokenResponseSchema } from './oauthEntries.js';
+export { shareQuerySchema } from './route.js';
+export { SERVER_CATALOG } from './serverCatalog.js';
+export { linkResponseSchema, resolvePathResponseSchema, rotateKeyResponseSchema, shareBodySchema, shareForBodySchema, shareForResponseSchema, shareResponseSchema } from './sharingEntries.js';
+export { eventQueueHealthSchema, serverHealthSchema, serviceProbeSchema } from './statusSchemas.js';
+export { authStatusQuerySchema, authStatusResponseSchema, healthResponseSchema, insiderKeyResponseSchema, pathKeyResponseSchema, searchBodySchema, searchResponseSchema, searchResultSchema, sendMagicLinkBodySchema, sendMagicLinkResponseSchema } from './utilitySchemas.js';

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

@@ -0,0 +1,125 @@
+/**
+ * The OAuth entries of the server catalog: start an authorization code flow, check stored credentials and get an access token. Pure.
+ *
+ * @packageDocumentation
+ */
+import { z } from 'zod';
+/** `oauthStart` body. */
+export declare const oauthStartBodySchema: z.ZodObject<{
+    provider: z.ZodString;
+    account: z.ZodString;
+    authUrl: z.ZodOptional<z.ZodString>;
+    tokenUrl: z.ZodOptional<z.ZodString>;
+    clientId: z.ZodString;
+    clientSecret: z.ZodString;
+    scopes: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    pkce: z.ZodOptional<z.ZodBoolean>;
+    origin: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+/** `oauthStart` response. */
+export declare const oauthStartResponseSchema: z.ZodObject<{
+    authUrl: z.ZodString;
+    state: z.ZodString;
+}, z.core.$strip>;
+/** `oauthStatus` and `oauthToken` query. */
+export declare const oauthCredentialQuerySchema: z.ZodObject<{
+    provider: z.ZodString;
+    account: z.ZodString;
+}, z.core.$strip>;
+/** `oauthStatus` response. */
+export declare const oauthStatusResponseSchema: z.ZodObject<{
+    exists: z.ZodBoolean;
+    expired: z.ZodBoolean;
+    provider: z.ZodString;
+    account: z.ZodString;
+}, z.core.$strip>;
+/** `oauthToken` response. */
+export declare const oauthTokenResponseSchema: z.ZodObject<{
+    access_token: z.ZodString;
+    token_type: z.ZodString;
+    expires_in_seconds: z.ZodNullable<z.ZodNumber>;
+}, z.core.$strip>;
+/** The OAuth entries. */
+export declare const OAUTH_ENTRIES: readonly [{
+    readonly body: z.ZodObject<{
+        provider: z.ZodString;
+        account: z.ZodString;
+        authUrl: z.ZodOptional<z.ZodString>;
+        tokenUrl: z.ZodOptional<z.ZodString>;
+        clientId: z.ZodString;
+        clientSecret: z.ZodString;
+        scopes: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        pkce: z.ZodOptional<z.ZodBoolean>;
+        origin: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+    readonly response: z.ZodObject<{
+        authUrl: z.ZodString;
+        state: z.ZodString;
+    }, 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: "write";
+    readonly name: "oauthStart";
+    readonly method: "POST";
+    readonly path: "/api/oauth/start";
+    readonly description: "Start an OAuth2 authorization code flow; returns the URL to open in a browser.";
+}, {
+    readonly query: z.ZodObject<{
+        provider: z.ZodString;
+        account: z.ZodString;
+    }, z.core.$strip>;
+    readonly response: z.ZodObject<{
+        exists: z.ZodBoolean;
+        expired: z.ZodBoolean;
+        provider: z.ZodString;
+        account: z.ZodString;
+    }, 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: "oauthStatus";
+    readonly method: "GET";
+    readonly path: "/api/oauth/status";
+    readonly description: "Check whether valid OAuth2 credentials exist for a provider/account.";
+}, {
+    readonly query: z.ZodObject<{
+        provider: z.ZodString;
+        account: z.ZodString;
+    }, z.core.$strip>;
+    readonly response: z.ZodObject<{
+        access_token: z.ZodString;
+        token_type: z.ZodString;
+        expires_in_seconds: z.ZodNullable<z.ZodNumber>;
+    }, 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: "oauthToken";
+    readonly method: "GET";
+    readonly path: "/api/oauth/token";
+    readonly description: "Get a valid access token for a provider/account, refreshing it when expired.";
+}];

package/dist/src/catalog/oauthEntries.js

@@ -0,0 +1,92 @@
+import { z } from 'zod';
+import { INSIDER_ONLY, route } from './route.js';
+
+/**
+ * The OAuth entries of the server catalog: start an authorization code flow, check stored credentials and get an access token. Pure.
+ *
+ * @packageDocumentation
+ */
+/** `oauthStart` body. */
+const oauthStartBodySchema = z.object({
+    /** Provider name (a configured provider supplies the defaults). */
+    provider: z.string().describe('Provider name.'),
+    /** Account name the credential is stored under. */
+    account: z.string().describe('Account name.'),
+    /** Authorization endpoint (default: the configured provider's). */
+    authUrl: z.string().optional().describe('Authorization endpoint URL.'),
+    /** Token endpoint (default: the configured provider's). */
+    tokenUrl: z.string().optional().describe('Token endpoint URL.'),
+    /** Client id. */
+    clientId: z.string().describe('OAuth client id.'),
+    /** Client secret. */
+    clientSecret: z.string().describe('OAuth client secret.'),
+    /** Scopes (default: the configured provider's). */
+    scopes: z.array(z.string()).optional().describe('Scopes to request.'),
+    /** Use PKCE (default: the configured provider's, else false). */
+    pkce: z.boolean().optional().describe('Use PKCE.'),
+    /** Origin of the redirect URI (default: the configured public URL). */
+    origin: z
+        .string()
+        .optional()
+        .describe('Origin for the redirect URI (default: the public URL).'),
+});
+/** `oauthStart` response. */
+const oauthStartResponseSchema = z.object({
+    /** URL to open in a browser. */
+    authUrl: z.string(),
+    /** The flow's state value. */
+    state: z.string(),
+});
+/** `oauthStatus` and `oauthToken` query. */
+const oauthCredentialQuerySchema = z.object({
+    /** Provider name. */
+    provider: z.string().describe('Provider name.'),
+    /** Account name. */
+    account: z.string().describe('Account name.'),
+});
+/** `oauthStatus` response. */
+const oauthStatusResponseSchema = z.object({
+    /** A credential file exists. */
+    exists: z.boolean(),
+    /** It has expired (or can't be read). */
+    expired: z.boolean(),
+    /** Provider asked for. */
+    provider: z.string(),
+    /** Account asked for. */
+    account: z.string(),
+});
+/** `oauthToken` response. */
+const oauthTokenResponseSchema = z.object({
+    /** Access token. */
+    access_token: z.string(),
+    /** Token type (normally `Bearer`). */
+    token_type: z.string(),
+    /** Seconds until expiry, or null when unknown. */
+    expires_in_seconds: z.number().nullable(),
+});
+/** The OAuth entries. */
+const OAUTH_ENTRIES = [
+    {
+        ...route('oauthStart', 'POST', '/api/oauth/start'),
+        body: oauthStartBodySchema,
+        response: oauthStartResponseSchema,
+        auth: INSIDER_ONLY,
+        kind: 'write',
+    },
+    {
+        ...route('oauthStatus', 'GET', '/api/oauth/status'),
+        query: oauthCredentialQuerySchema,
+        response: oauthStatusResponseSchema,
+        auth: INSIDER_ONLY,
+        kind: 'read',
+    },
+    {
+        ...route('oauthToken', 'GET', '/api/oauth/token'),
+        query: oauthCredentialQuerySchema,
+        response: oauthTokenResponseSchema,
+        auth: INSIDER_ONLY,
+        kind: 'read',
+    },
+];
+
+export { OAUTH_ENTRIES, oauthCredentialQuerySchema, oauthStartBodySchema, oauthStartResponseSchema, oauthStatusResponseSchema, oauthTokenResponseSchema };

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

@@ -0,0 +1,137 @@
+/**
+ * Shared parts of the jeeves-server catalog entries: the `route` helper (name, method, path, description), the auth specs of the access classes, the `*` path params and the share-credential query (`shareQuerySchema`). Pure.
+ *
+ * @remarks
+ * Auth specs are descriptive (jeeves spec Decision 80): the service's access
+ * hook enforces the access model. Identity and share credentials travel as
+ * the `k` query parameter or the `jeeves_session` cookie; the key-exchange
+ * routes take the raw machine seed in `X-API-Key`.
+ *
+ * @packageDocumentation
+ */
+import { z } from 'zod';
+import { ENTRY_DESCRIPTIONS } from './descriptions.js';
+/** The server's own entry names (other than the three standard ones). */
+export type ServerRouteName = keyof typeof ENTRY_DESCRIPTIONS;
+/**
+ * Name, method, path and description of a server entry.
+ *
+ * @param name - Entry name (also the SDK method, the plugin tool's base name
+ *   and the OpenAPI `operationId`).
+ * @param method - HTTP method.
+ * @param path - Route path (Fastify syntax).
+ * @returns The entry's identity fields.
+ */
+export declare function route<const N extends ServerRouteName, const M extends 'DELETE' | 'GET' | 'PATCH' | 'POST' | 'PUT', const P extends string>(name: N, method: M, path: P): {
+    readonly name: N;
+    readonly method: M;
+    readonly path: P;
+    readonly description: {
+        readonly health: "Liveness check: returns { ok: true }, with no downstream checks.";
+        readonly authStatus: "Check current authentication status. Returns whether authenticated, email, insider status, and key metadata.";
+        readonly sendMagicLink: "Request a sign-in link by email. Always answers with a verification URL, whether or not the email belongs to an insider.";
+        readonly drives: "List available root drives/labels configured on the server.";
+        readonly browse: "Get file or directory metadata. For files: size, mtime, content type, rendered HTML availability. For directories: listing of entries.";
+        readonly fileContent: "Get a file with type-specific handling: Markdown, CSV and diagrams rendered to HTML, other text as is, images and binaries by name. `raw=1` skips rendering.";
+        readonly fileWrite: "Overwrite the content of an existing file. Insider-only; the file must already exist.";
+        readonly fileMutate: "Apply a structured mutation to a .md file. Insider-only. Supports: edit-block, delete-block, insert-block, edit-cell, toggle-checkbox.";
+        readonly raw: "Download a file as is, with its own content type. `download=1` always sends it as an attachment.";
+        readonly export: "Export a Markdown document as PDF or DOCX, or a directory as a ZIP or Tar archive (archives for insiders only).";
+        readonly exportCacheClear: "Clear the export and diagram caches for a given path.";
+        readonly exportMermaid: "Export a Mermaid diagram file as SVG, PNG or PDF.";
+        readonly exportPlantUml: "Export a PlantUML diagram file in one of the formats the configured renderers support (SVG, PNG, PDF, EPS).";
+        readonly linkInfo: "Query available link types for a path (exists, page URL, raw URL, export links for PDF/DOCX/SVG/PNG).";
+        readonly diagram: "Get a diagram embedded in a rendered document, as SVG, by its type and content hash.";
+        readonly publicContent: "Get one of the public pages of the server (readme, privacy, terms) rendered as Markdown.";
+        readonly share: "Sign a share link for a path: a path key, optionally expiring, or a deep share (`depth`, `dirs`). The response reports whether the path is a directory.";
+        readonly shareFor: "Sign a share link for a path aimed at named insiders: an insider link when every recipient is an insider with access, else an outsider share checked against the outsider policy.";
+        readonly contentLink: "Pre-computed share link for one of the pinned content pages of the server (privacy, terms).";
+        readonly readmeLink: "Pre-computed share link for the README of the server.";
+        readonly resolvePath: "Convert an absolute filesystem path to a server browse path and optional public URL.";
+        readonly rotateKey: "Rotate the key of the calling insider. The old insider key and every outsider link the insider signed stop working.";
+        readonly pathKey: "Compute the outsider path key for a path from the machine seed sent in X-API-Key.";
+        readonly insiderKey: "Compute the insider key for the machine seed sent in X-API-Key.";
+        readonly search: "Semantic search through jeeves-watcher, grouped by file and filtered to the scopes of the caller.";
+        readonly searchFacets: "Search facets from jeeves-watcher, passed through unchanged.";
+        readonly receiveEvent: "Event gateway webhook receiver: matches a JSON object against the configured event schemas and queues the matching command.";
+        readonly listEvents: "Recent event log entries, newest last (insiders with no scopes configured; limit capped at 100).";
+        readonly oauthStart: "Start an OAuth2 authorization code flow; returns the URL to open in a browser.";
+        readonly oauthStatus: "Check whether valid OAuth2 credentials exist for a provider/account.";
+        readonly oauthToken: "Get a valid access token for a provider/account, refreshing it when expired.";
+        readonly runnerListJobs: "List the jeeves-runner jobs (runner GET /jobs).";
+        readonly runnerGetJob: "One jeeves-runner job (runner GET /jobs/:id).";
+        readonly runnerListRuns: "A jeeves-runner job's recent runs (runner GET /jobs/:id/runs).";
+        readonly runnerRunJob: "Run a jeeves-runner job now (runner POST /jobs/:id/run).";
+        readonly runnerEnableJob: "Enable a jeeves-runner job (runner PATCH /jobs/:id/enable).";
+        readonly runnerDisableJob: "Disable a jeeves-runner job (runner PATCH /jobs/:id/disable).";
+        readonly runnerStatus: "jeeves-runner status (runner GET /status).";
+    }[N];
+};
+/**
+ * `navigation` and `content` entries: an identity (session or insider key)
+ * or a share credential.
+ */
+export declare const KEY_OR_SESSION: {
+    readonly schemes: readonly [{
+        readonly in: "query";
+        readonly name: "k";
+    }, {
+        readonly in: "cookie";
+        readonly name: "jeeves_session";
+    }];
+};
+/**
+ * `insider`, `admin` and `content + insider` entries: an identity only
+ * (the service narrows `admin` to identities with no scopes).
+ */
+export declare const INSIDER_ONLY: {
+    readonly schemes: readonly [{
+        readonly in: "query";
+        readonly name: "k";
+    }, {
+        readonly in: "cookie";
+        readonly name: "jeeves_session";
+    }];
+    readonly insiderOnly: true;
+};
+/** `machineSeed` entries: the raw machine seed in `X-API-Key`. */
+export declare const MACHINE_SEED: {
+    readonly schemes: readonly [{
+        readonly in: "header";
+        readonly name: "X-API-Key";
+    }];
+};
+/** `eventKey` entries: a machine key valid for `/event`, as `k`. */
+export declare const EVENT_KEY: {
+    readonly schemes: readonly [{
+        readonly in: "query";
+        readonly name: "k";
+    }];
+};
+/** `public` entries. */
+export declare const PUBLIC: "none";
+/**
+ * Share-link parameters other than `k`, accepted by every content and
+ * navigation entry (and read by `authStatus`): an expiry, the deep-share
+ * fields and the legacy key parameter. All optional strings.
+ */
+export declare const shareQuerySchema: 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>;
+}, z.core.$strip>;
+/**
+ * The `*` path parameter: a browse path (`<root>/<path>`).
+ *
+ * @param description - What the path addresses.
+ * @returns The params schema.
+ */
+export declare const wildcardParams: (description: string) => z.ZodObject<{
+    '*': z.ZodString;
+}, z.core.$strip>;
+/** `*` of the content entries that address a file or a directory. */
+export declare const browsePathParams: z.ZodObject<{
+    '*': z.ZodString;
+}, z.core.$strip>;

package/dist/src/catalog/route.js

@@ -0,0 +1,92 @@
+import { z } from 'zod';
+import { ENTRY_DESCRIPTIONS } from './descriptions.js';
+
+/**
+ * Shared parts of the jeeves-server catalog entries: the `route` helper (name, method, path, description), the auth specs of the access classes, the `*` path params and the share-credential query (`shareQuerySchema`). Pure.
+ *
+ * @remarks
+ * Auth specs are descriptive (jeeves spec Decision 80): the service's access
+ * hook enforces the access model. Identity and share credentials travel as
+ * the `k` query parameter or the `jeeves_session` cookie; the key-exchange
+ * routes take the raw machine seed in `X-API-Key`.
+ *
+ * @packageDocumentation
+ */
+/**
+ * Name, method, path and description of a server entry.
+ *
+ * @param name - Entry name (also the SDK method, the plugin tool's base name
+ *   and the OpenAPI `operationId`).
+ * @param method - HTTP method.
+ * @param path - Route path (Fastify syntax).
+ * @returns The entry's identity fields.
+ */
+function route(name, method, path) {
+    return {
+        name,
+        method,
+        path,
+        description: ENTRY_DESCRIPTIONS[name],
+    };
+}
+/** The URL key (`k`): an insider, machine or share key. */
+const URL_KEY = { in: 'query', name: 'k' };
+/** The browser session cookie. */
+const SESSION_COOKIE = { in: 'cookie', name: 'jeeves_session' };
+/**
+ * `navigation` and `content` entries: an identity (session or insider key)
+ * or a share credential.
+ */
+const KEY_OR_SESSION = {
+    schemes: [URL_KEY, SESSION_COOKIE],
+};
+/**
+ * `insider`, `admin` and `content + insider` entries: an identity only
+ * (the service narrows `admin` to identities with no scopes).
+ */
+const INSIDER_ONLY = {
+    schemes: [URL_KEY, SESSION_COOKIE],
+    insiderOnly: true,
+};
+/** `machineSeed` entries: the raw machine seed in `X-API-Key`. */
+const MACHINE_SEED = {
+    schemes: [{ in: 'header', name: 'X-API-Key' }],
+};
+/** `eventKey` entries: a machine key valid for `/event`, as `k`. */
+const EVENT_KEY = { schemes: [URL_KEY] };
+/** `public` entries. */
+const PUBLIC = 'none';
+/**
+ * Share-link parameters other than `k`, accepted by every content and
+ * navigation entry (and read by `authStatus`): an expiry, the deep-share
+ * fields and the legacy key parameter. All optional strings.
+ */
+const shareQuerySchema = z.object({
+    /** Expiry (Unix ms) of an expiring share key. */
+    exp: z
+        .string()
+        .optional()
+        .describe('Share link expiry (Unix milliseconds), for expiring keys.'),
+    /** Deep share depth. */
+    d: z.string().optional().describe('Deep share depth.'),
+    /** Deep share: `1` when directories may be listed. */
+    dirs: z
+        .string()
+        .optional()
+        .describe('Deep share: 1 when directories below the shared path open.'),
+    /** Deep share stack (compressed). */
+    s: z.string().optional().describe('Deep share path stack.'),
+    /** Legacy name of `k`. */
+    key: z.string().optional().describe('Legacy name of the k parameter.'),
+});
+/**
+ * The `*` path parameter: a browse path (`<root>/<path>`).
+ *
+ * @param description - What the path addresses.
+ * @returns The params schema.
+ */
+const wildcardParams = (description) => z.object({ '*': z.string().describe(description) });
+/** `*` of the content entries that address a file or a directory. */
+const browsePathParams = wildcardParams('Browse path (e.g. "<drive>/path/to/file.md")');
+
+export { EVENT_KEY, INSIDER_ONLY, KEY_OR_SESSION, MACHINE_SEED, PUBLIC, browsePathParams, route, shareQuerySchema, wildcardParams };