@sigil-security/runtime 0.0.0

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/sigil.ts"],"sourcesContent":["// @sigil-security/runtime — Core Sigil instance (orchestration layer)\n// Reference: SPECIFICATION.md Sections 3, 5, 8\n\nimport {\n  WebCryptoCryptoProvider,\n  createKeyring,\n  rotateKey,\n  getActiveKey,\n  generateToken as coreGenerateToken,\n  validateToken as coreValidateToken,\n  computeContext,\n  generateOneShotToken as coreGenerateOneShotToken,\n  validateOneShotToken as coreValidateOneShotToken,\n  createNonceCache,\n  DEFAULT_TOKEN_TTL_MS,\n  DEFAULT_GRACE_WINDOW_MS,\n  DEFAULT_ONESHOT_TTL_MS,\n} from '@sigil-security/core'\nimport type { CryptoProvider, Keyring, NonceCache, ValidationResult } from '@sigil-security/core'\nimport {\n  createFetchMetadataPolicy,\n  createOriginPolicy,\n  createMethodPolicy,\n  createContentTypePolicy,\n  detectClientMode,\n  isProtectedMethod,\n  evaluatePolicyChain,\n  DEFAULT_HEADER_NAME,\n  DEFAULT_ONESHOT_HEADER_NAME,\n  DEFAULT_PROTECTED_METHODS,\n} from '@sigil-security/policy'\nimport type { PolicyValidator, RequestMetadata, PolicyChainResult } from '@sigil-security/policy'\nimport type {\n  SigilConfig,\n  SigilInstance,\n  ResolvedSigilConfig,\n  TokenGenerationResponse,\n  TokenValidationResponse,\n  ProtectResult,\n} from './types.js'\n\n// ============================================================\n// Master Secret Normalization\n// ============================================================\n\n/** Minimum master secret length in bytes for adequate security */\nconst MIN_MASTER_SECRET_BYTES = 32\n\n/**\n * Converts a string master secret to ArrayBuffer.\n * If already an ArrayBuffer, returns as-is.\n *\n * **Security (L1 fix):** Validates that the master secret is at least 32 bytes.\n * HKDF handles short inputs correctly, but effective security is bounded by\n * the input entropy. A weak master secret undermines the entire key hierarchy.\n *\n * @throws {Error} If the master secret is shorter than 32 bytes\n */\nfunction normalizeMasterSecret(secret: ArrayBuffer | string): ArrayBuffer {\n  if (typeof secret !== 'string') {\n    if (secret.byteLength < MIN_MASTER_SECRET_BYTES) {\n      throw new Error(\n        `Master secret must be at least ${String(MIN_MASTER_SECRET_BYTES)} bytes, ` +\n        `got ${String(secret.byteLength)} bytes. Use a cryptographically strong secret.`,\n      )\n    }\n    return secret\n  }\n  const encoder = new TextEncoder()\n  const bytes = encoder.encode(secret)\n  if (bytes.byteLength < MIN_MASTER_SECRET_BYTES) {\n    throw new Error(\n      `Master secret must be at least ${String(MIN_MASTER_SECRET_BYTES)} bytes when UTF-8 encoded, ` +\n      `got ${String(bytes.byteLength)} bytes. Use a cryptographically strong secret.`,\n    )\n  }\n  // Create a clean ArrayBuffer (not a view into a shared buffer)\n  const buffer = new ArrayBuffer(bytes.byteLength)\n  new Uint8Array(buffer).set(bytes)\n  return buffer\n}\n\n// ============================================================\n// Configuration Resolution\n// ============================================================\n\n/**\n * Resolves user config with defaults applied.\n */\nfunction resolveConfig(config: SigilConfig): ResolvedSigilConfig {\n  return {\n    tokenTTL: config.tokenTTL ?? DEFAULT_TOKEN_TTL_MS,\n    graceWindow: config.graceWindow ?? DEFAULT_GRACE_WINDOW_MS,\n    allowedOrigins: config.allowedOrigins,\n    legacyBrowserMode: config.legacyBrowserMode ?? 'degraded',\n    allowApiMode: config.allowApiMode ?? true,\n    protectedMethods: config.protectedMethods ?? DEFAULT_PROTECTED_METHODS,\n    contextBinding: config.contextBinding,\n    oneShotEnabled: config.oneShotEnabled ?? false,\n    oneShotTTL: config.oneShotTTL ?? DEFAULT_ONESHOT_TTL_MS,\n    headerName: config.headerName ?? DEFAULT_HEADER_NAME,\n    oneShotHeaderName: config.oneShotHeaderName ?? DEFAULT_ONESHOT_HEADER_NAME,\n    disableClientModeOverride: config.disableClientModeOverride ?? false,\n  }\n}\n\n// ============================================================\n// One-Shot Keyring Validation Helper\n// ============================================================\n\n/**\n * Validates a one-shot token against all keys in a keyring.\n *\n * One-shot tokens do NOT embed a kid, so we must try all keys.\n * The nonce is only consumed on the first successful validation.\n *\n * @returns The first successful result, or the last failure\n */\nasync function validateOneShotWithKeyring(\n  cryptoProvider: CryptoProvider,\n  keyring: Keyring,\n  tokenString: string,\n  expectedAction: string,\n  nonceCache: NonceCache,\n  expectedContext: Uint8Array | undefined,\n  ttlMs: number,\n): Promise<ValidationResult> {\n  let lastResult: ValidationResult = { valid: false, reason: 'no_keys' }\n\n  for (const key of keyring.keys) {\n    const result = await coreValidateOneShotToken(\n      cryptoProvider,\n      key,\n      tokenString,\n      expectedAction,\n      nonceCache,\n      expectedContext,\n      ttlMs,\n    )\n    if (result.valid) return result\n    lastResult = result\n  }\n\n  return lastResult\n}\n\n// ============================================================\n// Sigil Instance Factory\n// ============================================================\n\n/**\n * Creates a Sigil runtime instance.\n *\n * This is the main entry point for Sigil. It initializes keyrings,\n * sets up policy chains, and returns an orchestration instance\n * that adapters use for token generation, validation, and request protection.\n *\n * @param config - Sigil configuration\n * @returns Initialized SigilInstance\n *\n * @example\n * ```typescript\n * const sigil = await createSigil({\n *   masterSecret: process.env.CSRF_SECRET!,\n *   allowedOrigins: ['https://example.com'],\n * })\n *\n * // Generate a token\n * const result = await sigil.generateToken()\n *\n * // Protect a request\n * const protection = await sigil.protect(metadata)\n * ```\n */\nexport async function createSigil(config: SigilConfig): Promise<SigilInstance> {\n  const resolved = resolveConfig(config)\n  const cryptoProvider: CryptoProvider = config.cryptoProvider ?? new WebCryptoCryptoProvider()\n  const masterSecret = normalizeMasterSecret(config.masterSecret)\n\n  // Instance-scoped kid counter (avoids global state)\n  let kidCounter = 0\n  function nextKid(): number {\n    kidCounter = (kidCounter + 1) & 0xff // 8-bit wrap\n    return kidCounter\n  }\n\n  // Initialize CSRF keyring\n  const initialKid = nextKid()\n  let csrfKeyring = await createKeyring(cryptoProvider, masterSecret, initialKid, 'csrf')\n\n  // Initialize one-shot keyring and nonce cache (if enabled)\n  let oneShotKeyring: Keyring | null = null\n  let nonceCache: NonceCache | null = null\n  if (resolved.oneShotEnabled) {\n    oneShotKeyring = await createKeyring(cryptoProvider, masterSecret, initialKid, 'oneshot')\n    nonceCache = createNonceCache()\n  }\n\n  // Build policy chains\n  const browserPolicies: PolicyValidator[] = [\n    createMethodPolicy({ protectedMethods: [...resolved.protectedMethods] }),\n    createFetchMetadataPolicy({ legacyBrowserMode: resolved.legacyBrowserMode }),\n    createOriginPolicy({ allowedOrigins: [...resolved.allowedOrigins] }),\n    createContentTypePolicy(),\n  ]\n\n  const apiPolicies: PolicyValidator[] = [\n    createMethodPolicy({ protectedMethods: [...resolved.protectedMethods] }),\n    createContentTypePolicy(),\n  ]\n\n  // ============================================================\n  // Instance Methods\n  // ============================================================\n\n  const instance: SigilInstance = {\n    config: resolved,\n\n    async generateToken(\n      context?: readonly string[],\n    ): Promise<TokenGenerationResponse> {\n      const activeKey = getActiveKey(csrfKeyring)\n      if (activeKey === undefined) {\n        return { success: false, reason: 'no_active_key' }\n      }\n\n      let contextBytes: Uint8Array | undefined\n      if (context !== undefined && context.length > 0) {\n        contextBytes = await computeContext(cryptoProvider, ...context)\n      }\n\n      return coreGenerateToken(cryptoProvider, activeKey, contextBytes, resolved.tokenTTL)\n    },\n\n    async validateToken(\n      tokenString: string,\n      expectedContext?: readonly string[],\n    ): Promise<TokenValidationResponse> {\n      let contextBytes: Uint8Array | undefined\n      if (expectedContext !== undefined && expectedContext.length > 0) {\n        contextBytes = await computeContext(cryptoProvider, ...expectedContext)\n      }\n\n      return coreValidateToken(\n        cryptoProvider,\n        csrfKeyring,\n        tokenString,\n        contextBytes,\n        resolved.tokenTTL,\n        resolved.graceWindow,\n      )\n    },\n\n    async generateOneShotToken(\n      action: string,\n      context?: readonly string[],\n    ): Promise<TokenGenerationResponse> {\n      if (!resolved.oneShotEnabled || oneShotKeyring === null) {\n        return { success: false, reason: 'oneshot_not_enabled' }\n      }\n\n      const activeKey = getActiveKey(oneShotKeyring)\n      if (activeKey === undefined) {\n        return { success: false, reason: 'no_active_key' }\n      }\n\n      let contextBytes: Uint8Array | undefined\n      if (context !== undefined && context.length > 0) {\n        contextBytes = await computeContext(cryptoProvider, ...context)\n      }\n\n      return coreGenerateOneShotToken(\n        cryptoProvider,\n        activeKey,\n        action,\n        contextBytes,\n        resolved.oneShotTTL,\n      )\n    },\n\n    async validateOneShotToken(\n      tokenString: string,\n      expectedAction: string,\n      expectedContext?: readonly string[],\n    ): Promise<TokenValidationResponse> {\n      if (!resolved.oneShotEnabled || oneShotKeyring === null || nonceCache === null) {\n        return { valid: false, reason: 'oneshot_not_enabled' }\n      }\n\n      let contextBytes: Uint8Array | undefined\n      if (expectedContext !== undefined && expectedContext.length > 0) {\n        contextBytes = await computeContext(cryptoProvider, ...expectedContext)\n      }\n\n      // One-shot tokens have no kid — try all keys in the keyring\n      return validateOneShotWithKeyring(\n        cryptoProvider,\n        oneShotKeyring,\n        tokenString,\n        expectedAction,\n        nonceCache,\n        contextBytes,\n        resolved.oneShotTTL,\n      )\n    },\n\n    async rotateKeys(): Promise<void> {\n      const newKid = nextKid()\n      csrfKeyring = await rotateKey(csrfKeyring, cryptoProvider, masterSecret, newKid)\n\n      if (oneShotKeyring !== null) {\n        oneShotKeyring = await rotateKey(oneShotKeyring, cryptoProvider, masterSecret, newKid)\n      }\n    },\n\n    async protect(\n      metadata: RequestMetadata,\n      contextBindings?: readonly string[],\n    ): Promise<ProtectResult> {\n      // Step 1: Safe methods don't need protection\n      if (!isProtectedMethod(metadata.method, [...resolved.protectedMethods])) {\n        return {\n          allowed: true,\n          tokenValid: false,\n          policyResult: { allowed: true, evaluated: [], failures: [] },\n        }\n      }\n\n      // Step 2: Detect client mode\n      const mode = detectClientMode(metadata, {\n        disableClientModeOverride: resolved.disableClientModeOverride,\n      })\n\n      // Step 3: API mode check\n      if (mode === 'api' && !resolved.allowApiMode) {\n        return {\n          allowed: false,\n          reason: 'api_mode_not_allowed',\n          expired: false,\n          policyResult: null,\n        }\n      }\n\n      // Step 4: Run policy chain based on detected mode\n      const policies = mode === 'browser' ? browserPolicies : apiPolicies\n      const policyResult: PolicyChainResult = evaluatePolicyChain(policies, metadata)\n\n      if (!policyResult.allowed) {\n        return {\n          allowed: false,\n          reason: policyResult.reason,\n          expired: false,\n          policyResult,\n        }\n      }\n\n      // Step 5: Token must be present\n      if (metadata.tokenSource.from === 'none') {\n        return {\n          allowed: false,\n          reason: 'no_token_present',\n          expired: false,\n          policyResult,\n        }\n      }\n\n      // Step 6: Compute context binding (if provided)\n      let contextBytes: Uint8Array | undefined\n      if (contextBindings !== undefined && contextBindings.length > 0) {\n        contextBytes = await computeContext(cryptoProvider, ...contextBindings)\n      }\n\n      // Step 7: Validate CSRF token\n      const tokenResult = await coreValidateToken(\n        cryptoProvider,\n        csrfKeyring,\n        metadata.tokenSource.value,\n        contextBytes,\n        resolved.tokenTTL,\n        resolved.graceWindow,\n      )\n\n      if (!tokenResult.valid) {\n        return {\n          allowed: false,\n          reason: tokenResult.reason,\n          expired: tokenResult.reason === 'expired',\n          policyResult,\n        }\n      }\n\n      return {\n        allowed: true,\n        tokenValid: true,\n        policyResult,\n      }\n    },\n  }\n\n  return instance\n}\n"],"mappings":"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","names":[]}

package/dist/types-DySgT8rA.d.cts

@@ -0,0 +1,184 @@
+import { CryptoProvider } from '@sigil-security/core';
+import { RequestMetadata, PolicyChainResult, LegacyBrowserMode, ContextBindingConfig } from '@sigil-security/policy';
+
+/**
+ * Main configuration for Sigil runtime.
+ *
+ * This is the single entry point for configuring CSRF protection.
+ * The runtime layer orchestrates all interactions between core and policy.
+ *
+ * @example
+ * ```typescript
+ * const sigil = await createSigil({
+ *   masterSecret: process.env.CSRF_SECRET,
+ *   allowedOrigins: ['https://example.com'],
+ * })
+ * ```
+ */
+interface SigilConfig {
+    /** Master secret for HKDF key derivation (minimum 32 bytes recommended) */
+    readonly masterSecret: ArrayBuffer | string;
+    /** Token TTL in milliseconds (default: 20 minutes = 1_200_000ms) */
+    readonly tokenTTL?: number | undefined;
+    /** Grace window after TTL expiry for in-flight requests (default: 60s = 60_000ms) */
+    readonly graceWindow?: number | undefined;
+    /** List of allowed origins (e.g., ['https://example.com']) */
+    readonly allowedOrigins: readonly string[];
+    /** How to handle legacy browsers without Fetch Metadata (default: 'degraded') */
+    readonly legacyBrowserMode?: LegacyBrowserMode | undefined;
+    /** Allow API mode (non-browser clients with token-only validation) (default: true) */
+    readonly allowApiMode?: boolean | undefined;
+    /** HTTP methods that require CSRF protection (default: ['POST','PUT','PATCH','DELETE']) */
+    readonly protectedMethods?: readonly string[] | undefined;
+    /** Context binding configuration (risk tier model) */
+    readonly contextBinding?: ContextBindingConfig | undefined;
+    /** Enable one-shot token support (default: false) */
+    readonly oneShotEnabled?: boolean | undefined;
+    /** One-shot token TTL in milliseconds (default: 5 minutes = 300_000ms) */
+    readonly oneShotTTL?: number | undefined;
+    /** Custom header name for CSRF tokens (default: 'x-csrf-token') */
+    readonly headerName?: string | undefined;
+    /** Custom header name for one-shot tokens (default: 'x-csrf-one-shot-token') */
+    readonly oneShotHeaderName?: string | undefined;
+    /**
+     * Disable X-Client-Type header override for mode detection.
+     * When true, clients cannot self-declare as API mode to bypass
+     * Fetch Metadata and Origin validation policies.
+     *
+     * Enable this if CORS configuration cannot be tightly controlled.
+     * Default: false
+     */
+    readonly disableClientModeOverride?: boolean | undefined;
+    /** Custom CryptoProvider implementation (default: WebCryptoCryptoProvider) */
+    readonly cryptoProvider?: CryptoProvider | undefined;
+}
+/**
+ * Fully resolved configuration with all defaults applied.
+ * Exposed as `sigil.config` on a SigilInstance.
+ */
+interface ResolvedSigilConfig {
+    readonly tokenTTL: number;
+    readonly graceWindow: number;
+    readonly allowedOrigins: readonly string[];
+    readonly legacyBrowserMode: LegacyBrowserMode;
+    readonly allowApiMode: boolean;
+    readonly protectedMethods: readonly string[];
+    readonly contextBinding: ContextBindingConfig | undefined;
+    readonly oneShotEnabled: boolean;
+    readonly oneShotTTL: number;
+    readonly headerName: string;
+    readonly oneShotHeaderName: string;
+    readonly disableClientModeOverride: boolean;
+}
+/**
+ * The Sigil runtime instance.
+ *
+ * Created by `createSigil(config)`. Holds the keyring, nonce cache,
+ * and provides token generation / validation / protection methods.
+ */
+interface SigilInstance {
+    /** Generate a new CSRF token */
+    generateToken(context?: readonly string[]): Promise<TokenGenerationResponse>;
+    /** Validate a CSRF token */
+    validateToken(tokenString: string, expectedContext?: readonly string[]): Promise<TokenValidationResponse>;
+    /** Generate a one-shot token (requires `oneShotEnabled: true`) */
+    generateOneShotToken(action: string, context?: readonly string[]): Promise<TokenGenerationResponse>;
+    /** Validate a one-shot token (tries all keys in the oneshot keyring) */
+    validateOneShotToken(tokenString: string, expectedAction: string, expectedContext?: readonly string[]): Promise<TokenValidationResponse>;
+    /** Rotate keyrings — new key becomes active, oldest dropped */
+    rotateKeys(): Promise<void>;
+    /**
+     * Full request protection: policy chain + token validation.
+     *
+     * 1. Checks if the method needs protection
+     * 2. Detects client mode (browser vs API)
+     * 3. Runs appropriate policy chain
+     * 4. Validates CSRF token
+     *
+     * @param metadata - Normalized request metadata (extracted by adapter)
+     * @param contextBindings - Optional context bindings for token validation
+     */
+    protect(metadata: RequestMetadata, contextBindings?: readonly string[]): Promise<ProtectResult>;
+    /** Resolved configuration (readonly) */
+    readonly config: ResolvedSigilConfig;
+}
+/** Token generation response */
+type TokenGenerationResponse = {
+    readonly success: true;
+    readonly token: string;
+    readonly expiresAt: number;
+} | {
+    readonly success: false;
+    readonly reason: string;
+};
+/** Token validation response */
+type TokenValidationResponse = {
+    readonly valid: true;
+} | {
+    readonly valid: false;
+    readonly reason: string;
+};
+/**
+ * Result of full request protection (policy chain + token validation).
+ *
+ * - `allowed: true` → request passed all checks
+ * - `allowed: false` → request blocked, `reason` is for internal logging only
+ */
+type ProtectResult = {
+    readonly allowed: true;
+    readonly tokenValid: boolean;
+    readonly policyResult: PolicyChainResult;
+} | {
+    readonly allowed: false;
+    readonly reason: string;
+    readonly expired: boolean;
+    readonly policyResult: PolicyChainResult | null;
+};
+/**
+ * Extracts normalized `RequestMetadata` from a framework-specific request object.
+ *
+ * Each framework adapter implements this for its own request type.
+ * This bridges framework HTTP objects to the policy layer.
+ */
+type MetadataExtractor<TRequest> = (req: TRequest) => RequestMetadata;
+/** Minimal request shape for the token endpoint handler */
+interface TokenEndpointRequest {
+    readonly method: string;
+    readonly path: string;
+    readonly body?: Record<string, unknown> | undefined;
+}
+/** Token endpoint response (returned by `handleTokenEndpoint`) */
+interface TokenEndpointResult {
+    readonly handled: boolean;
+    readonly status: number;
+    readonly body: Record<string, unknown>;
+    readonly headers: Record<string, string>;
+}
+/** One-shot token request body */
+interface OneShotTokenRequestBody {
+    readonly action: string;
+    readonly context?: readonly string[] | undefined;
+}
+/** Uniform error response body — NEVER differentiates error types to client */
+interface ErrorResponseBody {
+    readonly error: string;
+}
+/**
+ * Options for framework middleware adapters.
+ *
+ * Controls path exclusion, token endpoint paths, and context binding extraction.
+ */
+interface MiddlewareOptions {
+    /** Paths to exclude from protection (exact match) */
+    readonly excludePaths?: readonly string[] | undefined;
+    /** Token generation endpoint path (default: '/api/csrf/token') */
+    readonly tokenEndpointPath?: string | undefined;
+    /** One-shot token endpoint path (default: '/api/csrf/one-shot') */
+    readonly oneShotEndpointPath?: string | undefined;
+}
+/** Default token generation endpoint path */
+declare const DEFAULT_TOKEN_ENDPOINT_PATH = "/api/csrf/token";
+/** Default one-shot token endpoint path */
+declare const DEFAULT_ONESHOT_ENDPOINT_PATH = "/api/csrf/one-shot";
+
+export { DEFAULT_ONESHOT_ENDPOINT_PATH as D, type ErrorResponseBody as E, type MetadataExtractor as M, type OneShotTokenRequestBody as O, type ProtectResult as P, type ResolvedSigilConfig as R, type SigilConfig as S, type TokenEndpointResult as T, type SigilInstance as a, DEFAULT_TOKEN_ENDPOINT_PATH as b, type MiddlewareOptions as c, type TokenEndpointRequest as d, type TokenGenerationResponse as e, type TokenValidationResponse as f };

package/dist/types-DySgT8rA.d.ts

@@ -0,0 +1,184 @@
+import { CryptoProvider } from '@sigil-security/core';
+import { RequestMetadata, PolicyChainResult, LegacyBrowserMode, ContextBindingConfig } from '@sigil-security/policy';
+
+/**
+ * Main configuration for Sigil runtime.
+ *
+ * This is the single entry point for configuring CSRF protection.
+ * The runtime layer orchestrates all interactions between core and policy.
+ *
+ * @example
+ * ```typescript
+ * const sigil = await createSigil({
+ *   masterSecret: process.env.CSRF_SECRET,
+ *   allowedOrigins: ['https://example.com'],
+ * })
+ * ```
+ */
+interface SigilConfig {
+    /** Master secret for HKDF key derivation (minimum 32 bytes recommended) */
+    readonly masterSecret: ArrayBuffer | string;
+    /** Token TTL in milliseconds (default: 20 minutes = 1_200_000ms) */
+    readonly tokenTTL?: number | undefined;
+    /** Grace window after TTL expiry for in-flight requests (default: 60s = 60_000ms) */
+    readonly graceWindow?: number | undefined;
+    /** List of allowed origins (e.g., ['https://example.com']) */
+    readonly allowedOrigins: readonly string[];
+    /** How to handle legacy browsers without Fetch Metadata (default: 'degraded') */
+    readonly legacyBrowserMode?: LegacyBrowserMode | undefined;
+    /** Allow API mode (non-browser clients with token-only validation) (default: true) */
+    readonly allowApiMode?: boolean | undefined;
+    /** HTTP methods that require CSRF protection (default: ['POST','PUT','PATCH','DELETE']) */
+    readonly protectedMethods?: readonly string[] | undefined;
+    /** Context binding configuration (risk tier model) */
+    readonly contextBinding?: ContextBindingConfig | undefined;
+    /** Enable one-shot token support (default: false) */
+    readonly oneShotEnabled?: boolean | undefined;
+    /** One-shot token TTL in milliseconds (default: 5 minutes = 300_000ms) */
+    readonly oneShotTTL?: number | undefined;
+    /** Custom header name for CSRF tokens (default: 'x-csrf-token') */
+    readonly headerName?: string | undefined;
+    /** Custom header name for one-shot tokens (default: 'x-csrf-one-shot-token') */
+    readonly oneShotHeaderName?: string | undefined;
+    /**
+     * Disable X-Client-Type header override for mode detection.
+     * When true, clients cannot self-declare as API mode to bypass
+     * Fetch Metadata and Origin validation policies.
+     *
+     * Enable this if CORS configuration cannot be tightly controlled.
+     * Default: false
+     */
+    readonly disableClientModeOverride?: boolean | undefined;
+    /** Custom CryptoProvider implementation (default: WebCryptoCryptoProvider) */
+    readonly cryptoProvider?: CryptoProvider | undefined;
+}
+/**
+ * Fully resolved configuration with all defaults applied.
+ * Exposed as `sigil.config` on a SigilInstance.
+ */
+interface ResolvedSigilConfig {
+    readonly tokenTTL: number;
+    readonly graceWindow: number;
+    readonly allowedOrigins: readonly string[];
+    readonly legacyBrowserMode: LegacyBrowserMode;
+    readonly allowApiMode: boolean;
+    readonly protectedMethods: readonly string[];
+    readonly contextBinding: ContextBindingConfig | undefined;
+    readonly oneShotEnabled: boolean;
+    readonly oneShotTTL: number;
+    readonly headerName: string;
+    readonly oneShotHeaderName: string;
+    readonly disableClientModeOverride: boolean;
+}
+/**
+ * The Sigil runtime instance.
+ *
+ * Created by `createSigil(config)`. Holds the keyring, nonce cache,
+ * and provides token generation / validation / protection methods.
+ */
+interface SigilInstance {
+    /** Generate a new CSRF token */
+    generateToken(context?: readonly string[]): Promise<TokenGenerationResponse>;
+    /** Validate a CSRF token */
+    validateToken(tokenString: string, expectedContext?: readonly string[]): Promise<TokenValidationResponse>;
+    /** Generate a one-shot token (requires `oneShotEnabled: true`) */
+    generateOneShotToken(action: string, context?: readonly string[]): Promise<TokenGenerationResponse>;
+    /** Validate a one-shot token (tries all keys in the oneshot keyring) */
+    validateOneShotToken(tokenString: string, expectedAction: string, expectedContext?: readonly string[]): Promise<TokenValidationResponse>;
+    /** Rotate keyrings — new key becomes active, oldest dropped */
+    rotateKeys(): Promise<void>;
+    /**
+     * Full request protection: policy chain + token validation.
+     *
+     * 1. Checks if the method needs protection
+     * 2. Detects client mode (browser vs API)
+     * 3. Runs appropriate policy chain
+     * 4. Validates CSRF token
+     *
+     * @param metadata - Normalized request metadata (extracted by adapter)
+     * @param contextBindings - Optional context bindings for token validation
+     */
+    protect(metadata: RequestMetadata, contextBindings?: readonly string[]): Promise<ProtectResult>;
+    /** Resolved configuration (readonly) */
+    readonly config: ResolvedSigilConfig;
+}
+/** Token generation response */
+type TokenGenerationResponse = {
+    readonly success: true;
+    readonly token: string;
+    readonly expiresAt: number;
+} | {
+    readonly success: false;
+    readonly reason: string;
+};
+/** Token validation response */
+type TokenValidationResponse = {
+    readonly valid: true;
+} | {
+    readonly valid: false;
+    readonly reason: string;
+};
+/**
+ * Result of full request protection (policy chain + token validation).
+ *
+ * - `allowed: true` → request passed all checks
+ * - `allowed: false` → request blocked, `reason` is for internal logging only
+ */
+type ProtectResult = {
+    readonly allowed: true;
+    readonly tokenValid: boolean;
+    readonly policyResult: PolicyChainResult;
+} | {
+    readonly allowed: false;
+    readonly reason: string;
+    readonly expired: boolean;
+    readonly policyResult: PolicyChainResult | null;
+};
+/**
+ * Extracts normalized `RequestMetadata` from a framework-specific request object.
+ *
+ * Each framework adapter implements this for its own request type.
+ * This bridges framework HTTP objects to the policy layer.
+ */
+type MetadataExtractor<TRequest> = (req: TRequest) => RequestMetadata;
+/** Minimal request shape for the token endpoint handler */
+interface TokenEndpointRequest {
+    readonly method: string;
+    readonly path: string;
+    readonly body?: Record<string, unknown> | undefined;
+}
+/** Token endpoint response (returned by `handleTokenEndpoint`) */
+interface TokenEndpointResult {
+    readonly handled: boolean;
+    readonly status: number;
+    readonly body: Record<string, unknown>;
+    readonly headers: Record<string, string>;
+}
+/** One-shot token request body */
+interface OneShotTokenRequestBody {
+    readonly action: string;
+    readonly context?: readonly string[] | undefined;
+}
+/** Uniform error response body — NEVER differentiates error types to client */
+interface ErrorResponseBody {
+    readonly error: string;
+}
+/**
+ * Options for framework middleware adapters.
+ *
+ * Controls path exclusion, token endpoint paths, and context binding extraction.
+ */
+interface MiddlewareOptions {
+    /** Paths to exclude from protection (exact match) */
+    readonly excludePaths?: readonly string[] | undefined;
+    /** Token generation endpoint path (default: '/api/csrf/token') */
+    readonly tokenEndpointPath?: string | undefined;
+    /** One-shot token endpoint path (default: '/api/csrf/one-shot') */
+    readonly oneShotEndpointPath?: string | undefined;
+}
+/** Default token generation endpoint path */
+declare const DEFAULT_TOKEN_ENDPOINT_PATH = "/api/csrf/token";
+/** Default one-shot token endpoint path */
+declare const DEFAULT_ONESHOT_ENDPOINT_PATH = "/api/csrf/one-shot";
+
+export { DEFAULT_ONESHOT_ENDPOINT_PATH as D, type ErrorResponseBody as E, type MetadataExtractor as M, type OneShotTokenRequestBody as O, type ProtectResult as P, type ResolvedSigilConfig as R, type SigilConfig as S, type TokenEndpointResult as T, type SigilInstance as a, DEFAULT_TOKEN_ENDPOINT_PATH as b, type MiddlewareOptions as c, type TokenEndpointRequest as d, type TokenGenerationResponse as e, type TokenValidationResponse as f };

package/package.json

@@ -0,0 +1,141 @@
+{
+  "name": "@sigil-security/runtime",
+  "version": "0.0.0",
+  "description": "Framework adapters — Express, Fastify, Hono, Oak, Elysia, native fetch",
+  "type": "module",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    },
+    "./express": {
+      "import": {
+        "types": "./dist/adapters/express.d.ts",
+        "default": "./dist/adapters/express.js"
+      },
+      "require": {
+        "types": "./dist/adapters/express.d.cts",
+        "default": "./dist/adapters/express.cjs"
+      }
+    },
+    "./fastify": {
+      "import": {
+        "types": "./dist/adapters/fastify.d.ts",
+        "default": "./dist/adapters/fastify.js"
+      },
+      "require": {
+        "types": "./dist/adapters/fastify.d.cts",
+        "default": "./dist/adapters/fastify.cjs"
+      }
+    },
+    "./hono": {
+      "import": {
+        "types": "./dist/adapters/hono.d.ts",
+        "default": "./dist/adapters/hono.js"
+      },
+      "require": {
+        "types": "./dist/adapters/hono.d.cts",
+        "default": "./dist/adapters/hono.cjs"
+      }
+    },
+    "./oak": {
+      "import": {
+        "types": "./dist/adapters/oak.d.ts",
+        "default": "./dist/adapters/oak.js"
+      },
+      "require": {
+        "types": "./dist/adapters/oak.d.cts",
+        "default": "./dist/adapters/oak.cjs"
+      }
+    },
+    "./elysia": {
+      "import": {
+        "types": "./dist/adapters/elysia.d.ts",
+        "default": "./dist/adapters/elysia.js"
+      },
+      "require": {
+        "types": "./dist/adapters/elysia.d.cts",
+        "default": "./dist/adapters/elysia.cjs"
+      }
+    },
+    "./fetch": {
+      "import": {
+        "types": "./dist/adapters/fetch.d.ts",
+        "default": "./dist/adapters/fetch.js"
+      },
+      "require": {
+        "types": "./dist/adapters/fetch.d.cts",
+        "default": "./dist/adapters/fetch.cjs"
+      }
+    }
+  },
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "keywords": [
+    "csrf",
+    "security",
+    "middleware",
+    "express",
+    "fastify",
+    "hono",
+    "oak",
+    "elysia",
+    "fetch",
+    "edge"
+  ],
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/laphilosophia/sigil-security.git",
+    "directory": "packages/runtime"
+  },
+  "dependencies": {
+    "@sigil-security/core": "0.0.0",
+    "@sigil-security/policy": "0.0.0"
+  },
+  "devDependencies": {
+    "tsup": "^8.0.0",
+    "typescript": "^5.7.0"
+  },
+  "peerDependencies": {
+    "express": ">=4.0.0",
+    "fastify": ">=4.0.0",
+    "hono": ">=4.0.0",
+    "@oakserver/oak": ">=12.0.0",
+    "elysia": ">=1.0.0"
+  },
+  "peerDependenciesMeta": {
+    "express": {
+      "optional": true
+    },
+    "fastify": {
+      "optional": true
+    },
+    "hono": {
+      "optional": true
+    },
+    "@oakserver/oak": {
+      "optional": true
+    },
+    "elysia": {
+      "optional": true
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc --noEmit"
+  }
+}