spine-framework 0.1.0

package/dist/functions/_shared/index.d.ts

@@ -0,0 +1,298 @@
+/**
+ * @module index
+ * @audience installer
+ * @layer shared-core
+ * @stability stable
+ *
+ * Spine v2 Core — Public Import Surface
+ *
+ * This is the **single, stable entry point** for all custom code importing
+ * Spine core functionality. Everything exported here is a committed contract.
+ * Internal helpers not listed here are free to change without notice.
+ *
+ * ## Usage
+ *
+ * ### In custom functions (v2-custom/functions/)
+ * ```ts
+ * import { runPipeline, adminDb, SYSTEM_PRINCIPAL, CoreContext } from '../_shared'
+ *
+ * const ctx: CoreContext = {
+ *   principal: SYSTEM_PRINCIPAL,
+ *   accountId: myAccountId,
+ *   db: adminDb,
+ *   requestId: crypto.randomUUID()
+ * }
+ * const result = await runPipeline(pipelineId, triggerData, ctx)
+ * ```
+ *
+ * ### In CLI commands
+ * ```ts
+ * import { runPipeline, adminDb, resolvePrincipal, CoreContext } from '../functions/_shared'
+ * ```
+ *
+ * ### Stability contract
+ * - All exports in this file are stable across patch and minor versions
+ * - Breaking changes require a major version bump and migration guide
+ * - Do NOT import from individual `_shared/*.ts` files directly — use this index
+ *
+ * @seeAlso middleware.ts (CoreContext, createHandler, HTTP helpers)
+ * @seeAlso principal.ts (Principal interface, SYSTEM_PRINCIPAL, resolvePrincipal)
+ * @seeAlso db.ts (adminDb, getUserDb, joins)
+ * @seeAlso pipeline-runner.ts (runPipeline, ExecutionResult)
+ * @seeAlso trigger-engine.ts (fire*Triggers, EventType)
+ * @seeAlso agent-runner.ts (runAgent, AgentConfig, InferenceResult)
+ * @seeAlso permissions.ts (PermissionEngine, sanitizeRecordData)
+ * @seeAlso schema-utils.ts (generateValidationSchema, ValidationSchema)
+ * @seeAlso audit.ts (emitAudit)
+ */
+/**
+ * CoreContext — the minimal execution context accepted by all Spine core functions.
+ * Construct one directly for import/CLI usage; API handlers get it from createHandler().
+ *
+ * @example
+ * ```ts
+ * const ctx: CoreContext = {
+ *   principal: SYSTEM_PRINCIPAL,
+ *   accountId: 'uuid-here',
+ *   db: adminDb,
+ *   requestId: crypto.randomUUID()
+ * }
+ * ```
+ */
+export type { CoreContext } from './middleware';
+/**
+ * RequestContext — CoreContext extended with HTTP-specific fields.
+ * Only needed if you are writing an API handler function.
+ */
+export type { RequestContext, HandlerFunction, HandlerResult } from './middleware';
+/**
+ * createHandler — wraps a handler function with auth, principal resolution, and audit.
+ * Use this when writing Netlify function handlers.
+ */
+export { createHandler, requireUserContext, requireSystemContextWithAudit, json, error as errorResponse, cors } from './middleware';
+/**
+ * Principal — unified identity for all actors (humans, machines, cron, triggers).
+ */
+export type { Principal } from './principal';
+/**
+ * resolvePrincipal — resolves a Principal from an incoming HTTP event.
+ * Used in custom handler wrappers.
+ */
+export { resolvePrincipal } from './principal';
+/**
+ * isSystemAdmin — returns true if principal has the system_admin role.
+ */
+export { isSystemAdmin } from './principal';
+/**
+ * machineHasScope — checks whether a machine principal has a given scope.
+ * Supports wildcards: "items:*", "*:*".
+ */
+export { machineHasScope, humanHasRole } from './principal';
+/**
+ * getPrincipalDb — returns the appropriate DB client for a principal.
+ * Humans get RLS-scoped client; machines get adminDb.
+ */
+export { getPrincipalDb } from './principal';
+/**
+ * formatPrincipalForAudit — structures a principal for audit log metadata.
+ */
+export { formatPrincipalForAudit } from './principal';
+/**
+ * ANONYMOUS_PRINCIPAL — static principal for unauthenticated requests.
+ */
+export { ANONYMOUS_PRINCIPAL } from './principal';
+/**
+ * SYSTEM_PRINCIPAL — static principal for internal system operations.
+ * Use this when constructing a CoreContext for CLI or import usage without
+ * a real authenticated user.
+ */
+export { SYSTEM_PRINCIPAL } from './principal';
+/**
+ * adminDb — Supabase service_role client. Bypasses RLS.
+ * Use for system operations, migrations, machine principal actions.
+ */
+export { adminDb } from './db';
+/**
+ * getUserDb — Returns a JWT-scoped Supabase client with RLS enforced.
+ * Use for human-principal requests.
+ */
+export { getUserDb } from './db';
+/**
+ * joins — PostgREST relationship hint strings for common FK relationships.
+ * @example `.select(\`*, \${joins.type}, \${joins.app}\`)`
+ */
+export { joins } from './db';
+export type { DbResult } from './db';
+/**
+ * runPipeline — execute a pipeline by ID with trigger data.
+ *
+ * @param pipelineId - UUID of the pipeline to run
+ * @param triggerData - Arbitrary data passed to all pipeline stages
+ * @param ctx - CoreContext (principal + accountId + db + requestId)
+ * @returns ExecutionResult with per-stage output and final status
+ * @throws If pipeline not found or inactive
+ *
+ * @example API handler
+ * ```ts
+ * const result = await runPipeline(body.pipeline_id, body.data, ctx)
+ * ```
+ *
+ * @example Custom import
+ * ```ts
+ * import { runPipeline, adminDb, SYSTEM_PRINCIPAL } from '../_shared'
+ * const ctx = { principal: SYSTEM_PRINCIPAL, accountId, db: adminDb, requestId: crypto.randomUUID() }
+ * const result = await runPipeline('uuid', { item_id: '...' }, ctx)
+ * ```
+ *
+ * @example CLI
+ * ```bash
+ * spine pipelines run <pipeline-id> --data '{"item_id":"..."}'
+ * ```
+ */
+export { runPipeline } from './pipeline-runner';
+export type { ExecutionResult, StageResult } from './pipeline-runner';
+/**
+ * checkAndFireTriggers — evaluate and fire all active triggers matching an event.
+ *
+ * @param eventType - e.g. 'item_created', 'account_updated'
+ * @param entityType - table name string
+ * @param entityId - UUID of the affected entity
+ * @param entityData - full entity data for condition evaluation
+ * @param ctx - CoreContext
+ *
+ * @example
+ * ```ts
+ * await checkAndFireTriggers('item_created', 'items', item.id, item, ctx)
+ * ```
+ */
+export { checkAndFireTriggers, fireCreateTriggers, fireUpdateTriggers, fireDeleteTriggers } from './trigger-engine';
+export type { EventType } from './trigger-engine';
+/**
+ * runAgent — run AI agent inference for a user message in a thread.
+ *
+ * Resolves agent config from thread → agent → prompt_config chain,
+ * assembles RAG context, calls LLM, handles tool dispatch and escalation.
+ *
+ * @param threadId - UUID of the thread
+ * @param userMessage - The user's message text
+ * @param ctx - CoreContext
+ * @returns Saved agent message record
+ *
+ * @example
+ * ```ts
+ * const msg = await runAgent(threadId, 'How do I reset my password?', ctx)
+ * ```
+ */
+export { runAgent, resolveAgentConfig } from './agent-runner';
+export type { AgentConfig, InferenceResult, ToolCall, ToolResult } from './agent-runner';
+/**
+ * PermissionEngine — the single source of truth for all authorization.
+ *
+ * @example
+ * ```ts
+ * const canRead = await PermissionEngine.canAccessRecord(ctx, record, 'read')
+ * const sanitized = await PermissionEngine.sanitizeRecordData(ctx, record, 'support_ticket')
+ * ```
+ */
+export { PermissionEngine } from './permissions';
+export type { PermissionResult } from './permissions';
+export { sanitizeRecordData, validateUpdatePermissions, canAccessRecord } from './permissions';
+/**
+ * generateValidationSchema — derive a structural validation schema from a design schema.
+ * Called automatically on type create/update; also useful in custom code.
+ */
+export { generateValidationSchema } from './schema-utils';
+export type { ValidationSchema } from './schema-utils';
+/**
+ * emitAudit — emit a structured audit log entry with full principal provenance.
+ *
+ * @param ctx - CoreContext
+ * @param action - e.g. 'items.create', 'pipeline.completed'
+ * @param target - { type, id, account_id }
+ * @param metadata - additional structured context
+ *
+ * @example
+ * ```ts
+ * await emitAudit(ctx, 'deal.stage_changed', { type: 'items', id: deal.id }, {
+ *   before: { stage: 'prospect' },
+ *   after: { stage: 'qualified' }
+ * })
+ * ```
+ */
+export { emitAudit } from './audit';
+/**
+ * resolveHandler — dynamically load a webhook handler by name.
+ *
+ * Used by integration-routes.ts to resolve handlers at runtime
+ * without static imports, enabling custom handlers to self-register.
+ *
+ * @param handlerName — The handler identifier from webhook_handlers table
+ * @returns Handler function or null if not found
+ *
+ * @example
+ * ```ts
+ * const handler = await resolveHandler('cortex-webhook')
+ * if (handler) await handler(event, context)
+ * ```
+ */
+export { resolveHandler, lookupHandler, loadHandler } from './webhook-registry';
+/**
+ * registerWebhookHandler — self-register a custom webhook handler.
+ *
+ * Use in custom Netlify functions to register as webhook handlers
+ * without modifying core code.
+ *
+ * @param config — Handler registration details
+ *
+ * @example
+ * ```ts
+ * import { registerWebhookHandler } from '@core/_shared'
+ * import { adminDb } from '@core/_shared'
+ *
+ * registerWebhookHandler({
+ *   name: 'my-handler',
+ *   functionName: 'custom_my-handler',
+ *   events: ['item.created']
+ * }, adminDb)
+ * ```
+ */
+export { registerWebhookHandler, deregisterWebhookHandler, isHandlerRegistered } from './webhook-registration';
+export type { WebhookHandlerRegistration } from './webhook-registration';
+/**
+ * loadManifest — load and parse an app manifest.json file.
+ *
+ * Used by apps.ts to merge database records with file-based
+ * app configuration (name, routes, nav_items, required_roles).
+ *
+ * @param manifestPath — Path to manifest.json relative to project root
+ * @returns Parsed AppManifest or null if not found/invalid
+ *
+ * @example
+ * ```ts
+ * const manifest = loadManifest('custom/apps/cortex/manifest.json')
+ * console.log(manifest.required_roles) // ['member']
+ * ```
+ */
+export { loadManifest, mergeWithManifest, clearManifestCache, discoverManifests } from './app-manifest';
+export type { AppManifest, NavItem } from './app-manifest';
+/**
+ * Testing utilities for custom code developers.
+ *
+ * Use these helpers to test your custom functions without
+ * full deployment. Includes mock contexts, principals, and
+ * assertion helpers.
+ *
+ * @example
+ * ```ts
+ * import { makeTestContext, mockPrincipal, cleanup } from '@core/testing'
+ *
+ * describe('My Handler', () => {
+ *   const ctx = makeTestContext({
+ *     principal: mockPrincipal({ roles: ['member'] })
+ *   })
+ * })
+ * ```
+ */
+export { makeTestContext, mockPrincipal, mockLogger, mockEvent, mockNetlifyContext, cleanup, setupTests, expectSuccessResponse, expectErrorResponse } from './testing';
+export type { TestContext, TestPrincipal, TestLogger } from './testing';
+//# sourceMappingURL=index.d.ts.map

package/dist/functions/_shared/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../.framework/functions/_shared/index.ts"],"names":[],"mappings":"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"}

package/dist/functions/_shared/middleware.d.ts

@@ -0,0 +1,315 @@
+/**
+ * @module middleware
+ * @audience both
+ * @layer shared-core
+ * @stability stable
+ *
+ * HTTP handler factory and request context types for all Spine Netlify functions.
+ * This module owns the boundary between raw HTTP events and the typed execution
+ * context (`RequestContext`) used by every handler. It also provides guard
+ * utilities (`requireUserContext`, `requireSystemContextWithAudit`) used to
+ * enforce authentication at the top of handlers.
+ *
+ * The key invariant: `createHandler` always resolves a `Principal` via
+ * `resolvePrincipal` before calling the inner handler. Handlers never receive
+ * an unauthenticated context — anonymous requests are rejected at the wrapper.
+ *
+ * IMPORTANT: `result.data` is never unwrapped in `createHandler`. Handlers
+ * return records directly. Unwrapping would collide with records that have a
+ * `.data` JSONB column.
+ *
+ * @seeAlso principal.ts (resolvePrincipal, getPrincipalDb, isSystemAdmin)
+ * @seeAlso audit.ts (emitAudit — called after every successful handler)
+ * @seeAlso db.ts (adminDb, getUserDb — selected by getPrincipalDb)
+ * @seeAlso index.ts (re-exports CoreContext, createHandler, requireUserContext)
+ */
+import { Principal } from './principal';
+/**
+ * Minimal execution context passed to all Spine core functions.
+ *
+ * This is the canonical context for `pipeline-runner`, `trigger-engine`,
+ * `agent-runner`, `audit`, and any custom code in `v2-custom/`. It contains
+ * only what core logic needs: identity, account scope, and a DB client.
+ *
+ * `RequestContext` (used inside HTTP handlers) extends this with HTTP-specific
+ * fields (`appId`, `query`). Direct importers and CLI callers construct
+ * `CoreContext` directly without going through `createHandler`.
+ *
+ * @inputSpec principal: Principal — must be a resolved principal (not null)
+ * @inputSpec accountId: string | null — null is allowed for system-level ops only
+ * @inputSpec db: SupabaseClient — use adminDb for system ops, getUserDb for RLS
+ * @inputSpec requestId: string — UUID; ties execution to audit log entries
+ * @calledBy pipeline-runner.ts, trigger-engine.ts, agent-runner.ts, audit.ts,
+ *   tests/integration/helpers.ts (makeTestCtx), cli/context.ts
+ *
+ * @example Import usage (v2-custom/)
+ * ```ts
+ * import { CoreContext, adminDb, SYSTEM_PRINCIPAL } from '../_shared/index'
+ * const ctx: CoreContext = {
+ *   principal: SYSTEM_PRINCIPAL,
+ *   accountId: 'uuid-of-account',
+ *   db: adminDb,
+ *   requestId: crypto.randomUUID()
+ * }
+ * await runPipeline(pipelineId, data, ctx)
+ * ```
+ *
+ * @example CLI usage
+ * ```bash
+ * # CLI constructs CoreContext from .xenv credentials automatically
+ * spine pipelines run <pipeline-id>
+ * ```
+ */
+export interface CoreContext {
+    /** Resolved principal for this execution */
+    principal: Principal;
+    /** Primary account scope — null for system-level operations */
+    accountId: string | null;
+    /** Database client — use adminDb for system ops, getUserDb for RLS-scoped */
+    db: any;
+    /** Unique ID for this execution (used in audit logs) */
+    requestId: string;
+}
+/**
+ * HTTP-layer execution context — extends `CoreContext` with request-specific fields.
+ *
+ * Constructed inside `createHandler` after principal resolution. Not used by
+ * core logic directly — core functions accept `CoreContext`. The extra fields
+ * are available to handlers that need them (e.g., `query.action`, `appId`).
+ *
+ * @inputSpec appId: string | null — from `x-app-id` header; null if absent
+ * @inputSpec query: Record<string, string> — parsed queryStringParameters from event
+ * @calledBy All 19 API handler functions (as the first argument)
+ * @seeAlso CoreContext (parent interface)
+ */
+export interface RequestContext extends CoreContext {
+    /** App ID from `x-app-id` header — used for app-scoped operations */
+    appId: string | null;
+    /** Parsed query string parameters from the Netlify event */
+    query: Record<string, string>;
+    /** Request path from the Netlify event */
+    requestPath: string;
+}
+/**
+ * Signature for all Spine HTTP handler functions.
+ *
+ * Every handler file exports a default that calls `createHandler(myHandler)`.
+ * The `body` parameter is the parsed JSON body, or null for GET requests.
+ *
+ * @inputSpec ctx: RequestContext — fully resolved context; never null
+ * @inputSpec body: any — parsed JSON body or null; undefined for GET requests
+ * @outputSpec Promise<any> — return value is wrapped in `{ data: result }` by createHandler
+ */
+export type HandlerFunction = (ctx: RequestContext, body?: any) => Promise<any>;
+/**
+ * Standard envelope shape returned by `createHandler` to the HTTP client.
+ *
+ * On success: `{ data: <handler result>, error: null, meta: { requestId, duration } }`
+ * On error: `{ data: null, error: <message> }` with appropriate HTTP status code.
+ *
+ * @outputSpec data: any — handler return value, never unwrapped
+ * @outputSpec error: string | undefined — error message; present only on failure
+ * @outputSpec meta: object | undefined — requestId + duration on success
+ */
+export interface HandlerResult {
+    data?: any;
+    error?: string;
+    meta?: any;
+}
+/**
+ * Wraps a handler function with principal resolution, request parsing, audit
+ * logging, and error handling. This is the entry point for every Netlify function.
+ *
+ * Execution flow:
+ *   1. Detect nested calls (event already has requestId + principal) → pass through
+ *   2. Generate `requestId`, parse headers, query params
+ *   3. Call `resolvePrincipal(event)` → reject anonymous with 401
+ *   4. Call `getPrincipalDb(principal)` → select correct DB client
+ *   5. Build `RequestContext`, parse + merge body
+ *   6. Call inner handler, measure duration
+ *   7. Emit `request.<method>` audit log (account-scoped requests only)
+ *   8. Return `json({ data: result, error: null, meta })` envelope
+ *   9. On any thrown error → return `error(message, 500)`
+ *
+ * @param handler - The inner handler function implementing the route logic
+ * @returns Netlify-compatible async function `(event, context) => Response`
+ * @throws never — all errors are caught and returned as HTTP 500
+ * @inputSpec handler: HandlerFunction — must return a Promise
+ * @outputSpec Netlify Lambda response object with statusCode, headers, body
+ * @sideEffects DB read: principal resolution (people, api_keys tables)
+ * @sideEffects DB write: emitAudit to logs table (account-scoped requests only)
+ * @calledBy Every function in functions/*.ts as the default export wrapper
+ * @calls resolvePrincipal, getPrincipalDb, emitAudit, json, error
+ * @testIntegration tests/integration/admin-data-accounts.test.ts
+ *
+ * @example API handler file pattern
+ * ```ts
+ * import { createHandler, RequestContext } from './_shared/middleware'
+ * export const handler = createHandler(async (ctx: RequestContext, body) => {
+ *   const action = ctx.query.action || 'list'
+ *   if (action === 'list') return listItems(ctx)
+ *   throw new Error(`Unknown action: ${action}`)
+ * })
+ * ```
+ */
+export declare function createHandler(handler: HandlerFunction): (event: any, context: any) => Promise<any>;
+/**
+ * Builds a JSON HTTP response object compatible with Netlify Functions.
+ *
+ * Always includes CORS headers permitting requests from any origin. Used
+ * internally by `createHandler` and directly by handlers that need a custom
+ * status code (e.g., 201 Created).
+ *
+ * @param data - Any JSON-serializable value to include as the response body
+ * @param status - HTTP status code (default: 200)
+ * @returns Netlify Lambda response object
+ * @throws never
+ * @inputSpec data: any — must be JSON-serializable; circular refs will throw at stringify
+ * @inputSpec status: number — valid HTTP status code (default 200)
+ * @outputSpec { statusCode, headers, body: string } — body is JSON.stringify(data)
+ * @sideEffects none
+ * @calledBy createHandler, error, cors, and directly by some handlers
+ * @testUnit none — trivial; verified by integration tests on every request
+ */
+export declare function json(data: any, status?: number): {
+    statusCode: number;
+    headers: {
+        'Content-Type': string;
+        'Access-Control-Allow-Origin': string;
+        'Access-Control-Allow-Headers': string;
+        'Access-Control-Allow-Methods': string;
+    };
+    body: string;
+};
+/**
+ * Builds a JSON error response with `{ data: null, error: message }` shape.
+ *
+ * Use this to return structured error responses from handlers. The message
+ * is safe to surface to clients — do not pass internal error details.
+ *
+ * @param message - Human-readable error message safe to return to client
+ * @param status - HTTP status code (default: 400)
+ * @returns Netlify Lambda response object
+ * @throws never
+ * @inputSpec message: string — client-safe error description
+ * @inputSpec status: number — HTTP status code (400, 401, 403, 404, 500)
+ * @outputSpec { statusCode: status, body: '{"data":null,"error":"<message>"}' }
+ * @sideEffects none
+ * @calledBy createHandler (on caught errors), requireUserContext,
+ *   requireSystemContextWithAudit, and many individual handlers
+ */
+export declare function error(message: string, status?: number): {
+    statusCode: number;
+    headers: {
+        'Content-Type': string;
+        'Access-Control-Allow-Origin': string;
+        'Access-Control-Allow-Headers': string;
+        'Access-Control-Allow-Methods': string;
+    };
+    body: string;
+};
+/**
+ * Parses the JSON body from a Netlify event object.
+ *
+ * Returns `null` if there is no body. Throws a descriptive error on malformed
+ * JSON so the error surfaces cleanly from `createHandler`'s catch block.
+ *
+ * @param event - Raw Netlify event object
+ * @returns Parsed body object or null
+ * @throws Error('Invalid JSON in request body') — when body is present but not valid JSON
+ * @inputSpec event.body: string | null | undefined — raw JSON string from HTTP request
+ * @outputSpec any — parsed JSON object, or null if no body
+ * @sideEffects none
+ * @calledBy Handlers that need body outside of createHandler's automatic parsing
+ */
+export declare function parseBody(event: any): any;
+/**
+ * Overloaded guard that requires a resolved human principal with an account scope.
+ *
+ * **Overload 1 — wrapper:** wrap a handler to enforce auth before it runs.
+ * **Overload 2 — inline:** call with `ctx` directly; returns an error response
+ *   object if auth is missing, or `null` if auth is present (allowing the
+ *   caller to do `const authErr = requireUserContext(ctx); if (authErr) return authErr`).
+ *
+ * Rejects requests where:
+ *   - `ctx.principal` is absent
+ *   - `ctx.principal.id === 'anonymous'`
+ *   - `ctx.accountId` is null or empty (machine principals without an account)
+ *
+ * @inputSpec ctx or handler: RequestContext or HandlerFunction
+ * @outputSpec HandlerFunction (overload 1) or HandlerResult | null (overload 2)
+ * @throws Error('User context required') — in wrapper mode if not authenticated
+ * @sideEffects none
+ * @calledBy API handlers that require an authenticated human with account scope
+ * @testIntegration tests/integration/isolation.test.ts
+ *
+ * @example Inline guard pattern (preferred)
+ * ```ts
+ * const authErr = requireUserContext(ctx)
+ * if (authErr) return authErr
+ * // ctx.principal and ctx.accountId are guaranteed non-null below here
+ * ```
+ *
+ * @example Wrapper pattern
+ * ```ts
+ * export const handler = createHandler(requireUserContext(async (ctx, body) => {
+ *   return listItems(ctx)
+ * }))
+ * ```
+ */
+export declare function requireUserContext(handler: HandlerFunction): HandlerFunction;
+export declare function requireUserContext(ctx: RequestContext): HandlerResult | null;
+/**
+ * Overloaded guard that requires a `system_admin` principal.
+ *
+ * **Overload 1 — wrapper:** wrap a handler; throws if not system_admin.
+ * **Overload 2 — inline:** call with `ctx`; returns error response or null.
+ *   Also accepts an optional `triggeredBy` string to set on the context for
+ *   audit trail chaining (e.g. pipeline execution ID).
+ *
+ * Rejects requests where:
+ *   - `ctx.principal` is absent or anonymous
+ *   - `ctx.principal` does not have the `system_admin` role
+ *
+ * @param arg - Handler to wrap, or RequestContext to validate inline
+ * @param triggeredBy - Optional: ID of the triggering entity (set on ctx)
+ * @returns HandlerFunction (overload 1) or HandlerResult | null (overload 2)
+ * @throws Error('System context required') — in wrapper mode if not system_admin
+ * @inputSpec ctx.principal.roles: string[] — must include 'system_admin'
+ * @outputSpec HandlerFunction | HandlerResult | null
+ * @sideEffects sets `ctx.triggeredBy` when validation passes (inline mode)
+ * @calledBy system-cron.ts, pipeline-executions.ts, and admin-only handlers
+ * @testIntegration tests/integration/isolation.test.ts
+ *
+ * @example Inline guard pattern
+ * ```ts
+ * const authErr = requireSystemContextWithAudit(ctx, 'cron-job-id')
+ * if (authErr) return authErr
+ * ```
+ */
+export declare function requireSystemContextWithAudit(handler: HandlerFunction): HandlerFunction;
+export declare function requireSystemContextWithAudit(ctx: RequestContext, triggeredBy?: string): HandlerResult | null;
+/**
+ * Returns a 200 JSON response for CORS preflight requests.
+ *
+ * Netlify automatically handles OPTIONS at the CDN level for most routes, but
+ * handlers that need to explicitly handle OPTIONS can call this.
+ *
+ * @returns json({ message: 'CORS enabled' }, 200) with CORS headers
+ * @throws never
+ * @inputSpec none
+ * @outputSpec Netlify Lambda response with CORS headers
+ * @sideEffects none
+ * @calledBy Handler files that explicitly handle OPTIONS method
+ */
+export declare function cors(): {
+    statusCode: number;
+    headers: {
+        'Content-Type': string;
+        'Access-Control-Allow-Origin': string;
+        'Access-Control-Allow-Headers': string;
+        'Access-Control-Allow-Methods': string;
+    };
+    body: string;
+};
+//# sourceMappingURL=middleware.d.ts.map

package/dist/functions/_shared/middleware.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"middleware.d.ts","sourceRoot":"","sources":["../../../.framework/functions/_shared/middleware.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,OAAO,EACL,SAAS,EAIV,MAAM,aAAa,CAAA;AAKpB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,MAAM,WAAW,WAAW;IAC1B,4CAA4C;IAC5C,SAAS,EAAE,SAAS,CAAA;IACpB,+DAA+D;IAC/D,SAAS,EAAE,MAAM,GAAG,IAAI,CAAA;IACxB,6EAA6E;IAC7E,EAAE,EAAE,GAAG,CAAA;IACP,wDAAwD;IACxD,SAAS,EAAE,MAAM,CAAA;CAClB;AAED;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,cAAe,SAAQ,WAAW;IACjD,qEAAqE;IACrE,KAAK,EAAE,MAAM,GAAG,IAAI,CAAA;IACpB,4DAA4D;IAC5D,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAC7B,0CAA0C;IAC1C,WAAW,EAAE,MAAM,CAAA;CACpB;AAED;;;;;;;;;GASG;AACH,MAAM,MAAM,eAAe,GAAG,CAAC,GAAG,EAAE,cAAc,EAAE,IAAI,CAAC,EAAE,GAAG,KAAK,OAAO,CAAC,GAAG,CAAC,CAAA;AAE/E;;;;;;;;;GASG;AACH,MAAM,WAAW,aAAa;IAC5B,IAAI,CAAC,EAAE,GAAG,CAAA;IACV,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,IAAI,CAAC,EAAE,GAAG,CAAA;CACX;AAID;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,eAAe,WAC/B,GAAG,WAAW,GAAG,kBAuGvC;AAID;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,IAAI,CAAC,IAAI,EAAE,GAAG,EAAE,MAAM,GAAE,MAAY;;;;;;;;;EAWnD;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,GAAE,MAAY;;;;;;;;;EAK1D;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,GAAG,GAAG,GAAG,CAQzC;AAID;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,eAAe,GAAG,eAAe,CAAA;AAC7E,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,cAAc,GAAG,aAAa,GAAG,IAAI,CAAA;AAmB7E;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,6BAA6B,CAAC,OAAO,EAAE,eAAe,GAAG,eAAe,CAAA;AACxF,wBAAgB,6BAA6B,CAAC,GAAG,EAAE,cAAc,EAAE,WAAW,CAAC,EAAE,MAAM,GAAG,aAAa,GAAG,IAAI,CAAA;AAgC9G;;;;;;;;;;;;GAYG;AACH,wBAAgB,IAAI;;;;;;;;;EAEnB"}