@alneas/eaos-server 0.0.0-stage → 0.2.0

package/dist/lifecycle-engine/platform/index.js

@@ -0,0 +1,60 @@
+import {
+  platformDatabaseTargets,
+  resolvePlatformDatabaseTarget,
+  validatePlatformRuntime
+} from "../../chunk-RHN4Y6VS.js";
+import {
+  parseSitePublicationPolicy
+} from "../../chunk-5TBBZIND.js";
+import {
+  initialPersonName,
+  parseAccountMemberships,
+  personKinds,
+  selectAccountTenant
+} from "../../chunk-XITLHDG3.js";
+import {
+  validatePlatformPackages
+} from "../../chunk-HCKAGLLB.js";
+import "../../chunk-55D4ERWO.js";
+import {
+  TenantDatabaseRouter
+} from "../../chunk-LOUGW6MU.js";
+import {
+  deploymentExecutionTarget,
+  deploymentPlacementHash,
+  resolveDeploymentPlacements,
+  summarizePlacedDeployment,
+  validateDeploymentPlacements
+} from "../../chunk-ZWZDLOE7.js";
+import {
+  deploymentActions,
+  deploymentComponentKinds,
+  summarizeDeployment,
+  validateDeploymentPlugins,
+  validateDeploymentReceipt,
+  validateDeploymentTarget
+} from "../../chunk-6CBVZ6CT.js";
+export {
+  TenantDatabaseRouter,
+  deploymentActions,
+  deploymentComponentKinds,
+  deploymentExecutionTarget,
+  deploymentPlacementHash,
+  initialPersonName,
+  parseAccountMemberships,
+  parseSitePublicationPolicy,
+  personKinds,
+  platformDatabaseTargets,
+  resolveDeploymentPlacements,
+  resolvePlatformDatabaseTarget,
+  selectAccountTenant,
+  summarizeDeployment,
+  summarizePlacedDeployment,
+  validateDeploymentPlacements,
+  validateDeploymentPlugins,
+  validateDeploymentReceipt,
+  validateDeploymentTarget,
+  validatePlatformPackages,
+  validatePlatformRuntime
+};
+//# sourceMappingURL=index.js.map

package/dist/lifecycle-engine/platform/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/lifecycle-engine/platform/runtime.d.ts

@@ -0,0 +1,80 @@
+import { BackendTarget } from '../index.js';
+import { PlatformPackage } from './artifacts.js';
+import '@alneas/eaos-core/contracts/data-contracts';
+import '@alneas/eaos-core/plugin-sdk';
+
+/**
+ * Nonsecret target catalog for routing databases within one shared execution host.
+ *
+ *
+ * Database placement inside one shared execution host. Targets reuse lifecycle identities.
+ * @see validatePlatformRuntime for canonical integration usage.
+ */
+interface PlatformRuntimeConfig {
+    /**
+     * Default target used for tenants without an explicit placement.
+     */
+    backend: BackendTarget;
+    /**
+     * Optional additional target definitions with distinct IDs.
+     */
+    databaseTargets?: BackendTarget[];
+    /**
+     * Optional verified tenant ID to configured target-ID map; dedicated additional targets require explicit entries.
+     */
+    tenantPlacements?: Record<string, string>;
+}
+/**
+ * Lists the default and additional configured database targets in declaration order.
+ * @param runtime - Platform runtime configuration; validate it before use.
+ * @returns A new array containing runtime.backend followed by databaseTargets; target objects are shared.
+ *
+ * @remarks
+ * Does not validate or deduplicate targets and performs no discovery or connection.
+ *
+ * @example
+ * ```typescript
+ * import { platformDatabaseTargets } from '@alneas/eaos-server/platform/runtime';
+ * const targets = platformDatabaseTargets({ backend: { id: 'main', databaseId: 'db-main', dialect: 'sqlite', mode: 'shared' } });
+ * ```
+ */
+declare function platformDatabaseTargets(runtime: PlatformRuntimeConfig): BackendTarget[];
+/**
+ * Validates explicit database placements and verifies that registered package tenants resolve to permitted targets.
+ * @param value - Untrusted runtime declaration, or undefined when no runtime is configured.
+ * @param packages - Validated package registrations whose tenant scopes must resolve; defaults to none.
+ * @returns The original runtime object when accepted, or undefined for absent configuration.
+ * @throws Error for malformed/duplicate targets, shared/dedicated scope mismatch, missing explicit placements or unresolved package tenants.
+ *
+ * @remarks
+ * Dedicated targets require unique physical database IDs and explicit placements unless they are the default backend. This checks nonsecret declarations only; host pools, provisioning and membership remain external.
+ *
+ * @example
+ * ```typescript
+ * import { validatePlatformRuntime } from '@alneas/eaos-server/platform/runtime';
+ * const runtime = validatePlatformRuntime({ backend: { id: 'main', databaseId: 'db-main', dialect: 'sqlite', mode: 'shared' } });
+ * ```
+ */
+declare function validatePlatformRuntime(value: unknown, packages?: PlatformPackage[]): PlatformRuntimeConfig | undefined;
+/**
+ * Resolves a verified tenant to its explicit placement or the configured default backend.
+ *
+ * Tenant comes from verified host membership, never raw request input. No implicit migration/fallback.
+ * @param runtime - Previously validated runtime configuration.
+ * @param tenantId - Verified concrete tenant from host membership, never raw request input.
+ * @returns The configured target object without cloning.
+ * @throws Error for missing/wildcard tenant or unavailable/mismatched target.
+ *
+ * @remarks
+ * Unmapped tenants use the configured default; a missing or dedicated-mismatched selected target fails rather than trying another database. No migration or database operation occurs.
+ *
+ * @example
+ * ```typescript
+ * import { resolvePlatformDatabaseTarget } from '@alneas/eaos-server/platform/runtime';
+ * const target = resolvePlatformDatabaseTarget({ backend: { id: 'main', databaseId: 'db-main', dialect: 'sqlite', mode: 'shared' } }, 'sample');
+ * ```
+ */
+declare function resolvePlatformDatabaseTarget(runtime: PlatformRuntimeConfig, tenantId: string): BackendTarget;
+
+export { platformDatabaseTargets, resolvePlatformDatabaseTarget, validatePlatformRuntime };
+export type { PlatformRuntimeConfig };

package/dist/lifecycle-engine/platform/runtime.js

@@ -0,0 +1,11 @@
+import {
+  platformDatabaseTargets,
+  resolvePlatformDatabaseTarget,
+  validatePlatformRuntime
+} from "../../chunk-RHN4Y6VS.js";
+export {
+  platformDatabaseTargets,
+  resolvePlatformDatabaseTarget,
+  validatePlatformRuntime
+};
+//# sourceMappingURL=runtime.js.map

package/dist/lifecycle-engine/platform/runtime.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/lifecycle-engine/platform/site-publication.d.ts

@@ -0,0 +1,102 @@
+/**
+ * Host-owned nonsecret publication mode and approval/trigger requirements; secret fields name bindings rather than contain secrets.
+ *
+ *
+ * Host-owned policy; secrets and executable commands are never configuration values.
+ * @see parseSitePublicationPolicy for canonical integration usage.
+ */
+type SitePublicationPolicy = {
+    /**
+     * Whether host workflow must obtain approval before publication; parsing does not grant approval.
+     */
+    requireApproval: boolean;
+    /**
+     * Operator initiation or CMS-published event; manual mode permits only operator.
+     */
+    trigger: 'operator' | 'cms-published';
+} & ({
+    /**
+     * Publication integration discriminator selecting its required nonsecret fields.
+     */
+    mode: 'pages-git';
+    /**
+     * Cloudflare account identifier, exactly 32 lowercase hexadecimal characters; not an access token.
+     */
+    accountId: string;
+    /**
+     * Registered Pages project slug, at most 63 lowercase letters/digits/hyphens.
+     */
+    project: string;
+    /**
+     * Reviewed Git branch reference without traversal or trailing slash.
+     */
+    branch: string;
+    /**
+     * Uppercase host secret-binding name for the deploy hook; never the hook value.
+     */
+    deployHookSecret: string;
+} | {
+    /**
+     * Publication integration discriminator selecting its required nonsecret fields.
+     */
+    mode: 'github-actions';
+    /**
+     * Reviewed GitHub owner/repository reference.
+     */
+    repository: string;
+    /**
+     * Reviewed workflow basename ending .yml or .yaml.
+     */
+    workflow: string;
+    /**
+     * Reviewed Git ref without traversal or trailing slash.
+     */
+    ref: string;
+    /**
+     * Uppercase host secret-binding name for the provider token; never the token value.
+     */
+    tokenSecret: string;
+} | {
+    /**
+     * Publication integration discriminator selecting its required nonsecret fields.
+     */
+    mode: 'artifact';
+    /**
+     * Registered artifact publication adapter ID, up to 100 letters/digits/underscore/hyphen characters.
+     */
+    provider: string;
+    /**
+     * Registered nonsecret artifact publication target ID.
+     */
+    target: string;
+} | {
+    /**
+     * Publication integration discriminator selecting its required nonsecret fields.
+     */
+    mode: 'manual';
+});
+/**
+ * Supported publication integration: Pages Git, GitHub Actions, artifact adapter or manual operator flow.
+ *
+ * @see parseSitePublicationPolicy for canonical integration usage.
+ */
+type SitePublicationMode = SitePublicationPolicy['mode'];
+/**
+ * Validates and clones a nonsecret host publication policy for one supported publication mode.
+ * @param value - Untrusted plain policy declaration with explicit mode, approval flag and trigger plus mode-specific references.
+ * @returns A structured clone narrowed to SitePublicationPolicy.
+ * @throws Error for unknown/extra fields, malformed provider references, invalid secret-reference names or unsupported trigger/mode combinations.
+ *
+ * @remarks
+ * Secret fields contain uppercase environment/binding names, never actual secret values. Manual publication requires operator trigger. Parsing does not execute publication, grant approval or contact a provider.
+ *
+ * @example
+ * ```typescript
+ * import { parseSitePublicationPolicy } from '@alneas/eaos-server/platform/site-publication';
+ * const policy = parseSitePublicationPolicy({ mode: 'manual', requireApproval: true, trigger: 'operator' });
+ * ```
+ */
+declare function parseSitePublicationPolicy(value: unknown): SitePublicationPolicy;
+
+export { parseSitePublicationPolicy };
+export type { SitePublicationMode, SitePublicationPolicy };

package/dist/lifecycle-engine/platform/site-publication.js

@@ -0,0 +1,7 @@
+import {
+  parseSitePublicationPolicy
+} from "../../chunk-5TBBZIND.js";
+export {
+  parseSitePublicationPolicy
+};
+//# sourceMappingURL=site-publication.js.map

package/dist/lifecycle-engine/platform/site-publication.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/lifecycle-engine/platform/user-directory.d.ts

@@ -0,0 +1,139 @@
+/**
+ * Host-verified tenant membership used for authorization, separate from business person records.
+ *
+ *
+ * Account membership is authorization data; business people do not grant access.
+ * @see parseAccountMemberships for canonical integration usage.
+ */
+interface AccountMembership {
+    /**
+     * Concrete tenant ID, at most 50 supported identifier characters.
+     */
+    tenantId: string;
+    /**
+     * Tenant-scoped role, at most 50 characters; platform-global role names are forbidden.
+     */
+    role: string;
+    /**
+     * Whether the membership currently grants tenant admission.
+     */
+    active: boolean;
+}
+/**
+ * Validated tenant memberships with optional explicit active default selection.
+ *
+ * @see parseAccountMemberships for canonical integration usage.
+ */
+interface AccountMemberships {
+    /**
+     * At most 1000 distinct tenant grants; empty means no tenant access.
+     */
+    memberships: readonly AccountMembership[];
+    /**
+     * Optional tenant among active memberships; omitted requires selection when multiple are active.
+     */
+    defaultTenantId?: string;
+}
+/**
+ * Supported business directory person categories; categories never grant account membership.
+ *
+ * @see parseAccountMemberships for canonical integration usage.
+ */
+declare const personKinds: readonly ["employee", "contractor", "partner_contact", "customer_contact", "other"];
+/**
+ * One supported business relationship category from personKinds.
+ *
+ * @see parseAccountMemberships for canonical integration usage.
+ */
+type PersonKind = typeof personKinds[number];
+/**
+ * Tenant-scoped business contact/person metadata that never grants authenticated membership.
+ *
+ * @see parseAccountMemberships for canonical integration usage.
+ */
+interface DirectoryPerson {
+    /**
+     * Business person record ID.
+     */
+    id: string;
+    /**
+     * Tenant owning this directory record.
+     */
+    tenantId: string;
+    /**
+     * Optional link to a host identity; linkage alone grants no access.
+     */
+    identityId?: string;
+    /**
+     * Stored display/legal name from explicit or verified creation inputs.
+     */
+    name: string;
+    /**
+     * Optional contact address; never used to manufacture a name.
+     */
+    email?: string;
+    /**
+     * Optional organization display text.
+     */
+    organizationName?: string;
+    /**
+     * Business relationship categories, independent of account roles.
+     */
+    kinds: readonly PersonKind[];
+    /**
+     * Business directory status, independent of login authorization.
+     */
+    active: boolean;
+}
+/**
+ * Normalizes bounded tenant memberships while rejecting duplicate tenant grants and platform-wide roles.
+ *
+ * Fail closed on malformed/duplicate membership data; provider metadata is host-owned.
+ * @param value - Host-owned verified provider metadata with at most 1000 membership entries and optional active defaultTenantId.
+ * @returns New membership records and an optional default tenant; unknown metadata fields are omitted.
+ * @throws Error for malformed IDs/roles, duplicate tenants, nonboolean active flags, forbidden global roles or a default outside active memberships.
+ *
+ * @remarks
+ * Tenant roles do not grant platform administration. Parsing validates shape, not metadata authenticity; business directory people never establish access.
+ *
+ * @example
+ * ```typescript
+ * import { parseAccountMemberships } from '@alneas/eaos-server/platform/user-directory';
+ * const account = parseAccountMemberships({ memberships: [{ tenantId: 'sample', role: 'member', active: true }], defaultTenantId: 'sample' });
+ * ```
+ */
+declare function parseAccountMemberships(value: unknown): AccountMemberships;
+/**
+ * Selects an account's declared default or its only active membership without choosing among multiple active tenants.
+ * @param account - Previously parsed AccountMemberships; this helper does not revalidate the default.
+ * @returns The default tenant, the sole active tenant, or undefined when explicit selection is needed/no active membership exists.
+ *
+ * @example
+ * ```typescript
+ * import { parseAccountMemberships, selectAccountTenant } from '@alneas/eaos-server/platform/user-directory';
+ * const tenantId = selectAccountTenant(parseAccountMemberships({ memberships: [{ tenantId: 'sample', role: 'member', active: true }] }));
+ * ```
+ */
+declare function selectAccountTenant(account: AccountMemberships): string | undefined;
+/**
+ * Chooses a trimmed explicit name or verified display name for initial person creation.
+ *
+ * Only at initial creation: require a real name, never manufacture one from email.
+ * @param explicitName - User-supplied name; nonstring/blank values fall back to verified display name.
+ * @param verifiedDisplayName - Trusted provider display name; email addresses are not synthesized into names.
+ * @returns The chosen trimmed nonblank name, at most 200 characters.
+ * @throws Error when both names are blank/nonstring or the chosen name exceeds 200 characters.
+ *
+ * @remarks
+ * Use only at initial registration; this helper does not update existing profiles or validate legal identity.
+ *
+ * @example
+ * ```typescript
+ * import { initialPersonName } from '@alneas/eaos-server/platform/user-directory';
+ * const name = initialPersonName('Sample Person', undefined);
+ * ```
+ */
+declare function initialPersonName(explicitName: unknown, verifiedDisplayName: unknown): string;
+
+export { initialPersonName, parseAccountMemberships, personKinds, selectAccountTenant };
+export type { AccountMembership, AccountMemberships, DirectoryPerson, PersonKind };

package/dist/lifecycle-engine/platform/user-directory.js

@@ -0,0 +1,13 @@
+import {
+  initialPersonName,
+  parseAccountMemberships,
+  personKinds,
+  selectAccountTenant
+} from "../../chunk-XITLHDG3.js";
+export {
+  initialPersonName,
+  parseAccountMemberships,
+  personKinds,
+  selectAccountTenant
+};
+//# sourceMappingURL=user-directory.js.map

package/dist/lifecycle-engine/platform/user-directory.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/mcp.d.ts

@@ -0,0 +1,92 @@
+import { Context, Hono } from 'hono';
+import { PluginEntitlementRuntime } from './entitlements/index.js';
+import { AIExecutionContext, AIHostAdapters, PluginRegistry, McpGatekeeper } from '@alneas/eaos-core';
+import 'hono/types';
+import './plugin-data/index.js';
+import '@alneas/eaos-core/plugin-sdk';
+import '@alneas/eaos-server/lifecycle-engine';
+
+/**
+ * Host-verified identity, roles, and enabled plugins used for MCP discovery and execution.
+ * @see createMcpRouter.
+ */
+interface McpPrincipal {
+    /** Nonblank authenticated user identifier. */
+    userId: string;
+    /** Nonblank authorized tenant identifier. */
+    tenantId: string;
+    /** Verified role strings passed to the gatekeeper; an empty array is permitted. */
+    roles: string[];
+    /** Exact installed plugin IDs, resolved from the server's current tenant configuration. */
+    enabledPluginIds: string[];
+}
+/**
+ * Shared registry and policy/audit service used by {@link createMcpRouter}.
+ */
+interface McpRuntime {
+    /** Registry supplying trusted manifests and executable tool handlers. Duplicate tool names fail discovery/execution. */
+    registry: PluginRegistry;
+    /** Current permission/approval policy and audit sink consulted for tool discovery and calls. */
+    gatekeeper: McpGatekeeper;
+}
+/**
+ * Live host authorization, resource injection, and bounded SSE-session settings for {@link createMcpRouter}.
+ */
+interface McpRouterOptions {
+    /** Runtime for declared commercial/usage entitlements; required by plugins whose rules need external entitlement checks. */
+    entitlements?: PluginEntitlementRuntime;
+    /** Additional current lifecycle gate; called on discovery and immediately before execution. */
+    isPluginEnabled?: (principal: McpPrincipal, pluginId: string) => Promise<boolean>;
+    /** Must verify authentication, tenant membership and enabled plugins on every request. */
+    resolvePrincipal: (context: Context) => Promise<McpPrincipal | null>;
+    /** Optional binding for a tenant-dedicated backend. */
+    tenantId?: string;
+    /** Inject already tenant-scoped resources; never pass an unrestricted administrative DB. */
+    createToolContext?: (principal: McpPrincipal, pluginId: string) => Promise<Record<string, unknown>>;
+    /** Resolve provider-neutral AI adapters after live authorization; the result is injected into the verified tool context. */
+    resolveAIHostAdapters?: (input: {
+        /**
+         * Verified current request principal after membership and enabled-plugin resolution.
+         */
+        principal: McpPrincipal;
+        /**
+         * Owning plugin whose admitted tool needs host AI adapters.
+         */
+        pluginId: string;
+        /**
+         * Exact registered MCP tool name being executed.
+         */
+        toolName: string;
+        /**
+         * Verified AI execution identity, operation mcp:toolName, and generated trace ID; no client scope overrides are accepted here.
+         */
+        context: AIExecutionContext;
+    }) => Promise<AIHostAdapters | undefined>;
+    /** Operational errors only; request bodies/credentials are not passed. */
+    onError?: (error: unknown) => void;
+    /** Maximum SSE session age and inactivity in milliseconds; finite values are floored and clamped to at least 1000. Defaults to 1800000 for absent/nonfinite input. */
+    sseSessionTtlMs?: number;
+    /** Per-router SSE session capacity; finite values are floored and clamped to at least 1. Defaults to 1000 for absent/nonfinite input. */
+    maxSseSessions?: number;
+}
+/**
+ * Creates authenticated MCP tool discovery/execution routes and an SSE JSON-RPC transport.
+ * @param runtime - Trusted plugin/tool registry and gatekeeper with audit behavior.
+ * @param options - Host principal verification, current lifecycle/entitlement checks, scoped dependencies, AI adapters, and SSE limits.
+ * @returns A Hono router exposing GET /tools, POST /execute, GET /sse, and POST /message; no network listener is started.
+ * @throws Router construction can propagate validator setup errors. Request-time callback, schema compilation, tool, or audit errors are passed to onError and normally rendered as a generic 500; a throwing onError can itself fail error handling.
+ * @remarks Every request resolves current identity and enabled plugins. Tool discovery hides unavailable tools; calls validate arguments, recheck lifecycle before execution, and perform entitlement admission. Human-approval requirements return pending data without executing the handler; no client approval flag bypasses this. Request bodies are limited to 1 MiB. Host callbacks must supply tenant-scoped resources and enforce real membership and lifecycle checks; the router does not open databases or persist results. SSE session state is process-local, owner-bound, capacity-limited, and removed on stream cancellation or lazy expiry checks. Expiry removes the mapping without explicitly closing the existing stream; no heartbeat or cross-process session sharing is provided. Tool failures may occur after side effects, so retry/idempotency remains host-owned.
+ * @example
+ * ```typescript
+ * import { createMcpRouter, type McpRuntime, type McpRouterOptions } from "@alneas/eaos-server/mcp";
+ * export function mcpRoutes(runtime: McpRuntime, options: McpRouterOptions) {
+ *   // options.resolvePrincipal must verify live identity, membership, and enabled plugins.
+ *   // Supply only tenant-scoped resources through createToolContext.
+ *   return createMcpRouter(runtime, options);
+ * }
+ * ```
+ */
+declare function createMcpRouter(runtime: McpRuntime, options: McpRouterOptions): Hono;
+
+export { createMcpRouter };
+export type { McpPrincipal, McpRouterOptions, McpRuntime };

package/dist/mcp.js

@@ -0,0 +1,10 @@
+import {
+  createMcpRouter
+} from "./chunk-VF5YDZJC.js";
+import "./chunk-46UWPEW2.js";
+import "./chunk-INCHXAFK.js";
+import "./chunk-3VITSHN3.js";
+export {
+  createMcpRouter
+};
+//# sourceMappingURL=mcp.js.map

package/dist/mcp.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/middleware/auth.d.ts

@@ -0,0 +1,118 @@
+import * as hono from 'hono';
+import { EaosUser, EaosEnv } from '@alneas/eaos-core';
+
+/**
+ * Host authentication adapters used by {@link createAuthMiddleware}.
+ * @remarks Results must come from verified credentials and trusted membership data; this middleware does not independently validate claims.
+ */
+interface AuthSessionVerifier {
+    /**
+     * Verifies a session before the optional API key fallback.
+     * @param authHeader - Raw Authorization header, or undefined if absent.
+     * @param cookieHeader - Raw Cookie header, or undefined if absent.
+     * @returns Session validity and trusted optional identity claims. pendingApproval takes priority over valid and produces 403.
+     * @throws Rejections propagate through request handling.
+     
+     * @example
+     * ```typescript
+     * import type { AuthSessionVerifier } from "@alneas/eaos-server";
+     * export async function inspectSession(verifier: AuthSessionVerifier, request: Request) {
+     *   // The host verifier checks real credentials; a header alone is not trusted.
+     *   const result = await verifier.verifySession(
+     *     request.headers.get("Authorization") ?? undefined,
+     *     request.headers.get("Cookie") ?? undefined,
+     *   );
+     *   return { valid: result.valid, pendingApproval: result.pendingApproval === true };
+     * }
+     * ```
+     */
+    verifySession(authHeader?: string, cookieHeader?: string): Promise<{
+        /** True only after successful trusted credential verification. */
+        valid: boolean;
+        /** Optional authenticated user ID copied to Hono context. */
+        userId?: string;
+        /** Optional verified email used when synthesizing a user object. */
+        email?: string;
+        /** Optional verified tenant claim; session middleware can continue without it, so downstream tenant admission remains required. */
+        tenantId?: string;
+        /** Trusted platform authority enabling X-Tenant-Id selection and synthesized super_admin role. */
+        isSuperAdmin?: boolean;
+        /** When truthy, produces a 403 before session validity or API-key fallback is considered. */
+        pendingApproval?: boolean;
+        /** Optional approval reference included in a pending response. */
+        pendingId?: string;
+        /** Optional trusted user object copied unchanged; if omitted with userId, middleware synthesizes one. */
+        user?: EaosUser;
+    }>;
+    /**
+     * Verifies a nonempty credential after session verification fails.
+     * @param token - Authorization value with a leading Bearer prefix removed case-insensitively.
+     * @returns Validity and trusted identity claims; a valid result also needs tenantId to grant access.
+     * @throws Adapter errors propagate through request handling.
+     
+     * @example
+     * ```typescript
+     * import type { AuthSessionVerifier } from "@alneas/eaos-server";
+     * export async function inspectApiKey(verifier: AuthSessionVerifier, token: string) {
+     *   if (!verifier.verifyApiKey) throw new Error("Host API-key verification is unavailable");
+     *   // Supply the actual credential without logging or persisting it here.
+     *   const result = await verifier.verifyApiKey(token);
+     *   return result.valid && !!result.tenantId;
+     * }
+     * ```
+     */
+    verifyApiKey?(token: string): Promise<{
+        /** True for a verified API key; tenantId is additionally required to continue. */
+        valid: boolean;
+        /** Required tenant claim for a successful middleware API-key fallback. */
+        tenantId?: string;
+        /** Optional authenticated key owner copied to userId; no user object is synthesized for this path. */
+        userId?: string;
+    }> | {
+        /**
+         * True only when the host has verified the presented API key; middleware also requires a truthy tenantId before continuing.
+         */
+        valid: boolean;
+        /**
+         * Trusted tenant claim required for successful API-key fallback; middleware does not verify tenant membership independently.
+         */
+        tenantId?: string;
+        /**
+         * Optional verified key-owner identity copied to request context; this fallback does not synthesize an EaosUser object.
+         */
+        userId?: string;
+    };
+}
+/**
+ * Authentication configuration for {@link createAuthMiddleware}.
+ */
+interface AuthMiddlewareOptions {
+    /** Host verifier; omission allows all requests through without establishing identity. */
+    verifier?: AuthSessionVerifier;
+    /** Case-sensitive path prefixes exempt from verification; defaults to /health, /metrics, and /api/health. An empty array disables these exemptions. */
+    skipPaths?: string[];
+}
+/**
+ * Resolves trusted session or API key claims into Hono context and rejects invalid credentials.
+ * @param options - Host verifier and excluded path prefixes; see {@link AuthMiddlewareOptions}.
+ * @returns Middleware that continues exempt or authenticated requests, returns 403 for pending approval, and otherwise returns 401.
+ * @throws Request execution propagates verifier and downstream middleware errors.
+ * @remarks Requests with both userId and tenantId already in context bypass verification. Omitting a verifier also bypasses authentication. Only session results marked isSuperAdmin may select X-Tenant-Id; the host remains responsible for tenant existence and authorization. A synthesized user gets super_admin or user roles; API key fallback sets no user object.
+ * @example
+ * ```typescript
+ * import { Hono } from "hono";
+ * import type { EaosEnv } from "@alneas/eaos-core";
+ * import { createAuthMiddleware, type AuthSessionVerifier } from "@alneas/eaos-server/middleware/auth";
+ * export function authenticatedApp(verifier: AuthSessionVerifier) {
+ *   // Supply a host adapter that actually validates sessions and tenant claims.
+ *   const app = new Hono<EaosEnv>();
+ *   app.use("*", createAuthMiddleware({ verifier, skipPaths: [] }));
+ *   app.get("/identity", c => c.json({ userId: c.get("userId") }));
+ *   return app;
+ * }
+ * ```
+ */
+declare function createAuthMiddleware(options?: AuthMiddlewareOptions): hono.MiddlewareHandler<EaosEnv, string, {}, Response>;
+
+export { createAuthMiddleware };
+export type { AuthMiddlewareOptions, AuthSessionVerifier };

package/dist/middleware/auth.js

@@ -0,0 +1,7 @@
+import {
+  createAuthMiddleware
+} from "../chunk-XIEY2OF4.js";
+export {
+  createAuthMiddleware
+};
+//# sourceMappingURL=auth.js.map

package/dist/middleware/auth.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}