@naylence/runtime 0.3.21 → 0.4.0

package/dist/types/naylence/fame/factory-manifest.d.ts

@@ -4,7 +4,7 @@
  *
  * Provides the list of runtime factory modules for registration.
  */
-export declare const MODULES: readonly ["./connector/broadcast-channel-connector-factory.js", "./connector/broadcast-channel-listener-factory.js", "./connector/http-listener-factory.js", "./connector/http-stateless-connector-factory.js", "./connector/inpage-connector-factory.js", "./connector/inpage-listener-factory.js", "./connector/websocket-connector-factory.js", "./connector/websocket-listener-factory.js", "./delivery/at-least-once-delivery-policy-factory.js", "./delivery/at-most-once-delivery-policy-factory.js", "./delivery/delivery-profile-factory.js", "./fabric/in-process-fame-fabric-factory.js", "./node/admission/admission-profile-factory.js", "./node/admission/direct-admission-client-factory.js", "./node/admission/noop-admission-client-factory.js", "./node/admission/welcome-service-client-factory.js", "./node/default-connection-retry-policy-factory.js", "./node/default-node-identity-policy-factory.js", "./node/node-factory.js", "./node/node-identity-policy-profile-factory.js", "./node/token-subject-node-identity-policy-factory.js", "./placement/static-node-placement-strategy-factory.js", "./security/auth/bearer-token-header-auth-injection-strategy-factory.js", "./security/auth/default-authorizer-factory.js", "./security/auth/jwks-jwt-token-verifier-factory.js", "./security/auth/jwt-token-issuer-factory.js", "./security/auth/jwt-token-verifier-factory.js", "./security/auth/no-auth-injection-strategy-factory.js", "./security/auth/none-token-provider-factory.js", "./security/auth/noop-authorizer-factory.js", "./security/auth/noop-token-issuer-factory.js", "./security/auth/noop-token-verifier-factory.js", "./security/auth/oauth2-authorizer-factory.js", "./security/auth/oauth2-client-credentials-token-provider-factory.js", "./security/auth/oauth2-pkce-token-provider-factory.js", "./security/auth/query-param-auth-injection-strategy-factory.js", "./security/auth/shared-secret-authorizer-factory.js", "./security/auth/shared-secret-token-provider-factory.js", "./security/auth/shared-secret-token-verifier-factory.js", "./security/auth/static-token-provider-factory.js", "./security/auth/websocket-subprotocol-auth-injection-strategy-factory.js", "./security/credential/dev-fixed-key-credential-provider-factory.js", "./security/credential/env-credential-provider-factory.js", "./security/credential/none-credential-provider-factory.js", "./security/credential/prompt-credential-provider-factory.js", "./security/credential/secret-store-credential-provider-factory.js", "./security/credential/session-key-credential-provider-factory.js", "./security/credential/static-credential-provider-factory.js", "./security/default-security-manager-factory.js", "./security/encryption/noop-encryption-manager-factory.js", "./security/encryption/noop-secure-channel-manager-factory.js", "./security/keys/default-key-manager-factory.js", "./security/keys/in-memory-key-store-factory.js", "./security/keys/noop-key-validator-factory.js", "./security/node-security-profile-factory.js", "./security/policy/default-security-policy-factory.js", "./security/policy/no-security-policy-factory.js", "./security/signing/eddsa-envelope-signer-factory.js", "./security/signing/eddsa-envelope-verifier-factory.js", "./security/trust-store/noop-trust-store-provider-factory.js", "./sentinel/capability-aware-routing-policy-factory.js", "./sentinel/composite-routing-policy-factory.js", "./sentinel/hybrid-path-routing-policy-factory.js", "./sentinel/load-balancing/composite-load-balancing-strategy-factory.js", "./sentinel/load-balancing/hrw-load-balancing-strategy-factory.js", "./sentinel/load-balancing/load-balancing-profile-factory.js", "./sentinel/load-balancing/random-load-balancing-strategy-factory.js", "./sentinel/load-balancing/round-robin-load-balancing-strategy-factory.js", "./sentinel/load-balancing/sticky-load-balancing-strategy-factory.js", "./sentinel/routing-profile-factory.js", "./sentinel/sentinel-factory.js", "./sentinel/store/route-store-factory.js", "./stickiness/simple-load-balancer-stickiness-manager-factory.js", "./telemetry/noop-trace-emitter-factory.js", "./telemetry/open-telemetry-trace-emitter-factory.js", "./telemetry/trace-emitter-profile-factory.js", "./welcome/default-welcome-service-factory.js"];
+export declare const MODULES: readonly ["./connector/broadcast-channel-connector-factory.js", "./connector/broadcast-channel-listener-factory.js", "./connector/http-listener-factory.js", "./connector/http-stateless-connector-factory.js", "./connector/inpage-connector-factory.js", "./connector/inpage-listener-factory.js", "./connector/websocket-connector-factory.js", "./connector/websocket-listener-factory.js", "./delivery/at-least-once-delivery-policy-factory.js", "./delivery/at-most-once-delivery-policy-factory.js", "./delivery/delivery-profile-factory.js", "./fabric/in-process-fame-fabric-factory.js", "./node/admission/admission-profile-factory.js", "./node/admission/direct-admission-client-factory.js", "./node/admission/noop-admission-client-factory.js", "./node/admission/welcome-service-client-factory.js", "./node/default-connection-retry-policy-factory.js", "./node/default-node-identity-policy-factory.js", "./node/node-factory.js", "./node/node-identity-policy-profile-factory.js", "./node/token-subject-node-identity-policy-factory.js", "./placement/static-node-placement-strategy-factory.js", "./security/auth/bearer-token-header-auth-injection-strategy-factory.js", "./security/auth/default-authorizer-factory.js", "./security/auth/default-policy-authorizer-factory.js", "./security/auth/jwks-jwt-token-verifier-factory.js", "./security/auth/jwt-token-issuer-factory.js", "./security/auth/jwt-token-verifier-factory.js", "./security/auth/no-auth-injection-strategy-factory.js", "./security/auth/none-token-provider-factory.js", "./security/auth/noop-authorizer-factory.js", "./security/auth/noop-token-issuer-factory.js", "./security/auth/noop-token-verifier-factory.js", "./security/auth/oauth2-authorizer-factory.js", "./security/auth/oauth2-client-credentials-token-provider-factory.js", "./security/auth/oauth2-pkce-token-provider-factory.js", "./security/auth/policy/basic-authorization-policy-factory.js", "./security/auth/policy/local-file-authorization-policy-source-factory.js", "./security/auth/query-param-auth-injection-strategy-factory.js", "./security/auth/shared-secret-authorizer-factory.js", "./security/auth/shared-secret-token-provider-factory.js", "./security/auth/shared-secret-token-verifier-factory.js", "./security/auth/static-token-provider-factory.js", "./security/auth/websocket-subprotocol-auth-injection-strategy-factory.js", "./security/credential/dev-fixed-key-credential-provider-factory.js", "./security/credential/env-credential-provider-factory.js", "./security/credential/none-credential-provider-factory.js", "./security/credential/prompt-credential-provider-factory.js", "./security/credential/secret-store-credential-provider-factory.js", "./security/credential/session-key-credential-provider-factory.js", "./security/credential/static-credential-provider-factory.js", "./security/default-security-manager-factory.js", "./security/encryption/noop-encryption-manager-factory.js", "./security/encryption/noop-secure-channel-manager-factory.js", "./security/keys/default-key-manager-factory.js", "./security/keys/in-memory-key-store-factory.js", "./security/keys/noop-key-validator-factory.js", "./security/node-security-profile-factory.js", "./security/policy/default-security-policy-factory.js", "./security/policy/no-security-policy-factory.js", "./security/signing/eddsa-envelope-signer-factory.js", "./security/signing/eddsa-envelope-verifier-factory.js", "./security/trust-store/noop-trust-store-provider-factory.js", "./sentinel/capability-aware-routing-policy-factory.js", "./sentinel/composite-routing-policy-factory.js", "./sentinel/hybrid-path-routing-policy-factory.js", "./sentinel/load-balancing/composite-load-balancing-strategy-factory.js", "./sentinel/load-balancing/hrw-load-balancing-strategy-factory.js", "./sentinel/load-balancing/load-balancing-profile-factory.js", "./sentinel/load-balancing/random-load-balancing-strategy-factory.js", "./sentinel/load-balancing/round-robin-load-balancing-strategy-factory.js", "./sentinel/load-balancing/sticky-load-balancing-strategy-factory.js", "./sentinel/routing-profile-factory.js", "./sentinel/sentinel-factory.js", "./sentinel/store/route-store-factory.js", "./stickiness/simple-load-balancer-stickiness-manager-factory.js", "./telemetry/noop-trace-emitter-factory.js", "./telemetry/open-telemetry-trace-emitter-factory.js", "./telemetry/trace-emitter-profile-factory.js", "./welcome/default-welcome-service-factory.js"];
 export type FactoryModuleSpec = (typeof MODULES)[number];
 export type FactoryModuleLoader = () => Promise<Record<string, unknown>>;
 export declare const MODULE_LOADERS: Record<FactoryModuleSpec, FactoryModuleLoader>;

package/dist/types/naylence/fame/node/node-event-listener.d.ts

@@ -4,6 +4,7 @@
 import type { FameAddress, FameConnector, FameDeliveryContext, FameEnvelope, NodeWelcomeFrame } from '@naylence/core';
 import type { AttachInfo } from './admission/node-attach-client.js';
 import type { NodeLike } from './node-like.js';
+import type { RouterState, RoutingAction } from '../sentinel/router.js';
 /**
  * Protocol for components that need to respond to node lifecycle events.
  *
@@ -132,6 +133,35 @@ export interface NodeEventListener {
      * @returns Transformed envelope for continued processing, or null to halt delivery
      */
     onDeliver?(node: NodeLike, envelope: FameEnvelope, context?: FameDeliveryContext): Promise<FameEnvelope | null>;
+    /**
+     * Called after routing policy has selected a RoutingAction but before it executes.
+     *
+     * This hook provides a single, centralized entry point for route authorization.
+     * It is invoked AFTER `routingPolicy.decide(...)` returns a RoutingAction and
+     * BEFORE `action.execute(...)` is called.
+     *
+     * Components implementing this hook can:
+     * - Authorize the selected routing action (ForwardUpstream, ForwardDownstream, etc.)
+     * - Replace the action with a Deny/Drop action to block unauthorized routes
+     * - Apply route-level security policies
+     * - Log or audit routing decisions
+     *
+     * Return semantics:
+     * - Return the RoutingAction to execute (either the `selected` action or a replacement).
+     * - If the hook returns `null`, `undefined`, or throws, the router will execute a
+     *   Drop action (envelope is dropped with NO_ROUTE nack).
+     *
+     * To allow the originally selected action, return `selected` directly.
+     * To deny/block, return a `Drop` or `Deny` action.
+     *
+     * @param node - The node performing the routing
+     * @param envelope - The envelope being routed
+     * @param selected - The RoutingAction selected by the routing policy
+     * @param state - The current router state (for context, not modification)
+     * @param context - Optional delivery context
+     * @returns The RoutingAction to execute (null/undefined/throw => Drop)
+     */
+    onRoutingActionSelected?(node: NodeLike, envelope: FameEnvelope, selected: RoutingAction, state: RouterState, context?: FameDeliveryContext | null): Promise<RoutingAction | null | undefined>;
     /**
      * Called when a node is about to forward an envelope upstream.
      *
@@ -325,6 +355,7 @@ export declare abstract class BaseNodeEventListener implements NodeEventListener
     onEnvelopeReceived?(_node: NodeLike, envelope: FameEnvelope, _context?: FameDeliveryContext): Promise<FameEnvelope | null>;
     onDeliverLocal?(_node: NodeLike, _address: FameAddress, envelope: FameEnvelope, _context?: FameDeliveryContext): Promise<FameEnvelope | null>;
     onDeliver?(_node: NodeLike, envelope: FameEnvelope, _context?: FameDeliveryContext): Promise<FameEnvelope | null>;
+    onRoutingActionSelected?(_node: NodeLike, _envelope: FameEnvelope, selected: RoutingAction, _state: RouterState, _context?: FameDeliveryContext | null): Promise<RoutingAction | null | undefined>;
     onForwardUpstream?(_node: NodeLike, envelope: FameEnvelope, _context?: FameDeliveryContext): Promise<FameEnvelope | null>;
     onForwardToRoute?(_node: NodeLike, _nextSegment: string, envelope: FameEnvelope, _context?: FameDeliveryContext): Promise<FameEnvelope | null>;
     onForwardToPeer?(_node: NodeLike, _peerSegment: string, envelope: FameEnvelope, _context?: FameDeliveryContext): Promise<FameEnvelope | null>;

package/dist/types/naylence/fame/security/auth/authorizer.d.ts

@@ -1,7 +1,44 @@
 import type { AuthorizationContext, FameDeliveryContext, FameEnvelope } from '@naylence/core';
 import type { NodeLike } from '../../node/node-like.js';
+import type { RuleAction } from './policy/authorization-policy-definition.js';
+/**
+ * Route authorization result returned by authorizeRoute.
+ */
+export interface RouteAuthorizationResult {
+    /**
+     * Whether the route action is authorized.
+     */
+    authorized: boolean;
+    /**
+     * The authorization context (if authorized).
+     */
+    authContext?: AuthorizationContext;
+    /**
+     * Reason for denial (for internal logging only, not for on-wire disclosure).
+     */
+    denialReason?: string;
+    /**
+     * Matched rule ID (for logging/audit).
+     */
+    matchedRule?: string;
+}
 export interface Authorizer {
     authenticate(credentials: string | Uint8Array): Promise<AuthorizationContext | undefined>;
     authorize(node: NodeLike, envelope: FameEnvelope, context?: FameDeliveryContext): Promise<AuthorizationContext | undefined>;
+    /**
+     * Authorizes a routing action after the routing decision has been made.
+     *
+     * This method is called with the explicitly mapped action token from the
+     * routing decision (ForwardUpstream, ForwardDownstream, ForwardPeer,
+     * DeliverLocal). It does NOT receive RoutingAction objects to avoid
+     * coupling authorization logic to routing execution behavior.
+     *
+     * @param node - The node handling the request
+     * @param envelope - The FAME envelope being routed
+     * @param action - The authorization action token (route-oriented)
+     * @param context - Optional delivery context
+     * @returns RouteAuthorizationResult if implemented, or undefined to allow
+     */
+    authorizeRoute?(node: NodeLike, envelope: FameEnvelope, action: RuleAction, context?: FameDeliveryContext): Promise<RouteAuthorizationResult | undefined>;
     createReverseAuthorizationConfig?(node: NodeLike): Promise<Record<string, unknown> | undefined> | Record<string, unknown> | undefined;
 }

package/dist/types/naylence/fame/security/auth/default-policy-authorizer-factory.d.ts

@@ -0,0 +1,55 @@
+import type { Authorizer } from './authorizer.js';
+import { AuthorizerFactory, type AuthorizerConfig } from './authorizer-factory.js';
+import { type TokenVerifierConfig } from './token-verifier-factory.js';
+import { type AuthorizationPolicySourceConfig } from './policy/authorization-policy-source-factory.js';
+import { type AuthorizationPolicyConfig } from './policy/authorization-policy-factory.js';
+/**
+ * Configuration for DefaultPolicyAuthorizer.
+ */
+export interface DefaultPolicyAuthorizerConfig extends AuthorizerConfig {
+    type: 'PolicyAuthorizer';
+    /**
+     * Token verifier configuration.
+     */
+    verifier?: TokenVerifierConfig | Record<string, unknown> | null;
+    /**
+     * Authorization policy configuration.
+     * Either policy or policySource must be provided.
+     */
+    policy?: AuthorizationPolicyConfig | Record<string, unknown> | null;
+    /**
+     * Authorization policy source configuration.
+     * Either policy or policySource must be provided.
+     */
+    policySource?: AuthorizationPolicySourceConfig | Record<string, unknown> | null;
+    policy_source?: AuthorizationPolicySourceConfig | Record<string, unknown> | null;
+}
+/**
+ * Factory metadata for registration.
+ */
+export declare const FACTORY_META: {
+    readonly base: "AuthorizerFactory";
+    readonly key: "PolicyAuthorizer";
+};
+/**
+ * Factory for creating DefaultPolicyAuthorizer instances.
+ *
+ * This factory uses lazy loading to avoid pulling in Node.js-specific
+ * code in browser environments.
+ */
+export declare class DefaultPolicyAuthorizerFactory extends AuthorizerFactory<DefaultPolicyAuthorizerConfig> {
+    readonly type = "PolicyAuthorizer";
+    readonly isDefault = true;
+    /**
+     * Creates a DefaultPolicyAuthorizer from the given configuration.
+     *
+     * @param config - Configuration for the authorizer
+     * @param factoryArgs - Additional factory arguments:
+     *   - TokenVerifier instance
+     *   - AuthorizationPolicy instance
+     *   - AuthorizationPolicySource instance
+     * @returns The created authorizer
+     */
+    create(config?: DefaultPolicyAuthorizerConfig | Record<string, unknown> | null, ...factoryArgs: unknown[]): Promise<Authorizer>;
+}
+export default DefaultPolicyAuthorizerFactory;

package/dist/types/naylence/fame/security/auth/default-policy-authorizer.d.ts

@@ -0,0 +1,99 @@
+import type { AuthorizationContext, FameDeliveryContext, FameEnvelope } from '@naylence/core';
+import type { NodeLike } from '../../node/node-like.js';
+import type { PolicyAuthorizer } from './policy-authorizer.js';
+import type { AuthorizationPolicy } from './policy/authorization-policy.js';
+import type { AuthorizationPolicySource } from './policy/authorization-policy-source.js';
+import type { TokenVerifier } from './token-verifier.js';
+import type { TokenVerifierProvider } from './token-verifier-provider.js';
+import type { RouteAuthorizationResult } from './authorizer.js';
+import type { RuleAction } from './policy/authorization-policy-definition.js';
+/**
+ * Options for creating a DefaultPolicyAuthorizer.
+ */
+export interface DefaultPolicyAuthorizerOptions {
+    /**
+     * Token verifier for authenticating credentials.
+     */
+    tokenVerifier?: TokenVerifier;
+    token_verifier?: TokenVerifier;
+    /**
+     * The authorization policy to use for authorization decisions.
+     * Either policy or policySource must be provided.
+     */
+    policy?: AuthorizationPolicy;
+    /**
+     * A source to load the authorization policy from.
+     * Either policy or policySource must be provided.
+     */
+    policySource?: AuthorizationPolicySource;
+    policy_source?: AuthorizationPolicySource;
+}
+/**
+ * An authorizer that delegates authorization decisions to a pluggable policy.
+ *
+ * This authorizer combines token-based authentication with policy-based
+ * authorization. The token verifier handles authentication (validating
+ * credentials), while the authorization policy handles authorization
+ * decisions (allow/deny based on the request context).
+ */
+export declare class DefaultPolicyAuthorizer implements PolicyAuthorizer, TokenVerifierProvider {
+    private tokenVerifierImpl?;
+    private policyImpl?;
+    private readonly policySource?;
+    private policyLoaded;
+    constructor(options?: DefaultPolicyAuthorizerOptions);
+    /**
+     * The currently active authorization policy.
+     */
+    get policy(): AuthorizationPolicy;
+    /**
+     * The token verifier used for authentication.
+     */
+    get tokenVerifier(): TokenVerifier;
+    set tokenVerifier(verifier: TokenVerifier);
+    /**
+     * Ensures the authorization policy is loaded.
+     * If using a policy source, loads the policy from it.
+     */
+    ensurePolicyLoaded(): Promise<void>;
+    /**
+     * Reloads the authorization policy from the policy source.
+     * Only works if a policy source was configured.
+     */
+    reloadPolicy(): Promise<void>;
+    /**
+     * Authenticates credentials and returns an authorization context.
+     *
+     * @param credentials - The credentials to authenticate (token string or bytes)
+     * @returns The authorization context if authentication succeeds, undefined otherwise
+     */
+    authenticate(credentials: string | Uint8Array): Promise<AuthorizationContext | undefined>;
+    /**
+     * Authorizes a request using the configured authorization policy.
+     *
+     * For NodeAttach frames, evaluates policy with action='Connect'.
+     * For other frames, this method performs basic authentication validation
+     * but does NOT infer send/receive actions. Route-level authorization
+     * is handled separately via authorizeRoute().
+     *
+     * @param node - The node handling the request
+     * @param envelope - The FAME envelope being authorized
+     * @param context - Optional delivery context
+     * @returns The authorization context if authorized, undefined if denied
+     */
+    authorize(node: NodeLike, envelope: FameEnvelope, context?: FameDeliveryContext): Promise<AuthorizationContext | undefined>;
+    /**
+     * Authorizes a routing action after the routing decision has been made.
+     *
+     * This method evaluates the authorization policy with the explicitly
+     * provided action token (ForwardUpstream, ForwardDownstream, ForwardPeer,
+     * DeliverLocal).
+     *
+     * @param node - The node handling the request
+     * @param envelope - The FAME envelope being routed
+     * @param action - The authorization action token from the routing decision
+     * @param context - Optional delivery context
+     * @returns RouteAuthorizationResult with authorization decision
+     */
+    authorizeRoute(node: NodeLike, envelope: FameEnvelope, action: RuleAction, context?: FameDeliveryContext): Promise<RouteAuthorizationResult | undefined>;
+}

package/dist/types/naylence/fame/security/auth/oauth2-authorizer-factory.d.ts

@@ -25,6 +25,8 @@ export interface OAuth2AuthorizerConfig extends AuthorizerConfig {
     reverse_auth_ttl_sec?: number;
     enforceTokenSubjectNodeIdentity?: boolean;
     enforce_token_subject_node_identity?: boolean;
+    trustedClientScope?: string;
+    trusted_client_scope?: string;
 }
 export declare const FACTORY_META: {
     readonly base: "AuthorizerFactory";

package/dist/types/naylence/fame/security/auth/oauth2-authorizer.d.ts

@@ -15,6 +15,7 @@ export interface OAuth2AuthorizerOptions {
     maxTtlSec?: number;
     reverseAuthTtlSec?: number;
     enforceTokenSubjectNodeIdentity?: boolean;
+    trustedClientScope?: string;
 }
 export declare class OAuth2Authorizer implements Authorizer, TokenVerifierProvider, NodeEventListener {
     readonly priority = 1000;
@@ -25,6 +26,7 @@ export declare class OAuth2Authorizer implements Authorizer, TokenVerifierProvid
     private readonly requireScope;
     private readonly reverseAuthTtlSec;
     private readonly enforceTokenSubjectNodeIdentity;
+    private readonly trustedClientScope;
     private node?;
     constructor(rawOptions: OAuth2AuthorizerOptions | Record<string, unknown>);
     get tokenVerifier(): TokenVerifier;

package/dist/types/naylence/fame/security/auth/policy/authorization-policy-definition.d.ts

@@ -0,0 +1,166 @@
+/**
+ * Authorization policy definition types.
+ *
+ * This module defines the schema for authorization policies that can be
+ * loaded from YAML/JSON files and evaluated at runtime.
+ */
+/**
+ * The effect of an authorization rule.
+ */
+export type RuleEffect = 'allow' | 'deny';
+/**
+ * The action type a rule applies to (route-oriented, DX-friendly tokens).
+ *
+ * These tokens represent "what will happen next" in routing, not inferred send/receive:
+ * - Connect: NodeAttach connection handshake (pre-routing)
+ * - ForwardUpstream: Envelope will be forwarded to parent node
+ * - ForwardDownstream: Envelope will be forwarded to a child route
+ * - ForwardPeer: Envelope will be forwarded to a peer node
+ * - DeliverLocal: Envelope will be delivered to a local address handler
+ * - '*': Matches all actions (wildcard)
+ */
+export type RuleAction = 'Connect' | 'ForwardUpstream' | 'ForwardDownstream' | 'ForwardPeer' | 'DeliverLocal' | '*';
+/**
+ * Scope requirement using logical operators.
+ *
+ * Supports recursive nesting with a maximum depth enforced at parse time.
+ */
+export type ScopeRequirement = string | {
+    any_of: ScopeRequirement[];
+} | {
+    all_of: ScopeRequirement[];
+} | {
+    none_of: ScopeRequirement[];
+};
+/**
+ * Normalized scope requirement with explicit type discriminator.
+ */
+export type NormalizedScopeRequirement = {
+    type: 'pattern';
+    pattern: string;
+} | {
+    type: 'any_of';
+    requirements: NormalizedScopeRequirement[];
+} | {
+    type: 'all_of';
+    requirements: NormalizedScopeRequirement[];
+} | {
+    type: 'none_of';
+    requirements: NormalizedScopeRequirement[];
+};
+/**
+ * An authorization rule definition.
+ */
+export interface AuthorizationRuleDefinition {
+    /**
+     * Optional unique identifier for the rule.
+     * Used in decision traces for debugging.
+     */
+    id?: string;
+    /**
+     * Optional human-readable description of the rule.
+     */
+    description?: string;
+    /**
+     * The effect when this rule matches: allow or deny.
+     */
+    effect: RuleEffect;
+    /**
+     * The action type this rule applies to.
+     * Can be a single action or an array of actions (implicit any-of).
+     * @default '*' (all actions)
+     */
+    action?: RuleAction | RuleAction[];
+    /**
+     * Address pattern(s) to match using glob syntax.
+     * Can be a single pattern or an array (implicit any-of).
+     * If omitted, matches all addresses.
+     *
+     * Glob syntax:
+     * - `*` matches any characters except dots (single segment)
+     * - `**` matches any characters including dots (any depth)
+     * - `?` matches a single character (not a dot)
+     * - Other characters are matched literally
+     *
+     * Note: In OSS/basic policy, patterns are always treated as globs.
+     * Patterns starting with `^` are NOT interpreted as regex.
+     */
+    address?: string | string[];
+    /**
+     * Optional frame type gating.
+     * Can be a single frame type string or an array (implicit any-of).
+     * Matching is case-insensitive.
+     */
+    frame_type?: string | string[];
+    /**
+     * Optional delivery origin type gating.
+     * Can be a single origin type or an array (implicit any-of).
+     * Valid values: 'downstream', 'upstream', 'peer', 'local'.
+     * Matching is case-insensitive with whitespace trimmed.
+     * If omitted, matches any origin type.
+     * If specified but context.originType is undefined, rule does not match.
+     */
+    origin_type?: string | string[];
+    /**
+     * Scope requirement for the rule to match.
+     * If omitted, no scope check is performed.
+     */
+    scope?: ScopeRequirement;
+    /**
+     * Expression condition (reserved for advanced-security package).
+     * Basic policy parser ignores this field.
+     */
+    when?: string;
+    /**
+     * Allow additional fields for forward compatibility.
+     * Unknown fields are ignored with a warning.
+     */
+    [key: string]: unknown;
+}
+/**
+ * Authorization policy definition loaded from a file.
+ */
+export interface AuthorizationPolicyDefinition {
+    /**
+     * Schema version for the policy format.
+     */
+    version: string;
+    /**
+     * Default effect when no rule matches.
+     */
+    default_effect: RuleEffect;
+    /**
+     * List of authorization rules, evaluated in order.
+     * First matching rule determines the outcome.
+     */
+    rules: AuthorizationRuleDefinition[];
+    /**
+     * Allow additional fields for forward compatibility.
+     */
+    [key: string]: unknown;
+}
+/**
+ * Maximum nesting depth for scope requirements.
+ */
+export declare const MAX_SCOPE_NESTING_DEPTH = 5;
+/**
+ * Known fields in AuthorizationPolicyDefinition.
+ */
+export declare const KNOWN_POLICY_FIELDS: Set<string>;
+/**
+ * Known fields in AuthorizationRuleDefinition.
+ * Fields not in this set trigger a warning.
+ */
+export declare const KNOWN_RULE_FIELDS: Set<string>;
+/**
+ * Valid action values.
+ */
+export declare const VALID_ACTIONS: readonly RuleAction[];
+/**
+ * Valid origin type values (lowercase, matching DeliveryOriginType string values).
+ */
+export declare const VALID_ORIGIN_TYPES: readonly string[];
+/**
+ * Valid effect values.
+ */
+export declare const VALID_EFFECTS: readonly RuleEffect[];

package/dist/types/naylence/fame/security/auth/policy/authorization-policy-factory.d.ts

@@ -0,0 +1,38 @@
+import type { CreateResourceOptions, ResourceConfig } from '@naylence/factory';
+import { AbstractResourceFactory } from '@naylence/factory';
+import type { AuthorizationPolicy } from './authorization-policy.js';
+/**
+ * Base type identifier for authorization policy factories.
+ */
+export declare const AUTHORIZATION_POLICY_FACTORY_BASE_TYPE = "AuthorizationPolicyFactory";
+/**
+ * Configuration for creating an authorization policy.
+ */
+export interface AuthorizationPolicyConfig extends ResourceConfig {
+    type: string;
+    [key: string]: unknown;
+}
+/**
+ * Abstract factory base class for creating authorization policies.
+ *
+ * Implementations of this factory create specific types of authorization
+ * policies (e.g., expression-based, rule-based, etc.).
+ */
+export declare abstract class AuthorizationPolicyFactory<C extends AuthorizationPolicyConfig = AuthorizationPolicyConfig> extends AbstractResourceFactory<AuthorizationPolicy, C> {
+    /**
+     * Creates an authorization policy from the given configuration.
+     *
+     * @param config - Configuration for the policy
+     * @param factoryArgs - Additional factory arguments
+     * @returns The created authorization policy
+     */
+    abstract create(config?: C | Record<string, unknown> | null, ...factoryArgs: unknown[]): Promise<AuthorizationPolicy>;
+    /**
+     * Static helper to create an authorization policy using the factory registry.
+     *
+     * @param config - Configuration for the policy
+     * @param options - Resource creation options
+     * @returns The created policy, or undefined if no factory matched
+     */
+    static createAuthorizationPolicy<C extends AuthorizationPolicyConfig = AuthorizationPolicyConfig>(config?: C | Record<string, unknown> | null, options?: CreateResourceOptions): Promise<AuthorizationPolicy | undefined>;
+}

package/dist/types/naylence/fame/security/auth/policy/authorization-policy-source-factory.d.ts

@@ -0,0 +1,38 @@
+import type { CreateResourceOptions, ResourceConfig } from '@naylence/factory';
+import { AbstractResourceFactory } from '@naylence/factory';
+import type { AuthorizationPolicySource } from './authorization-policy-source.js';
+/**
+ * Base type identifier for authorization policy source factories.
+ */
+export declare const AUTHORIZATION_POLICY_SOURCE_FACTORY_BASE_TYPE = "AuthorizationPolicySourceFactory";
+/**
+ * Configuration for creating an authorization policy source.
+ */
+export interface AuthorizationPolicySourceConfig extends ResourceConfig {
+    type: string;
+    [key: string]: unknown;
+}
+/**
+ * Abstract factory base class for creating authorization policy sources.
+ *
+ * Implementations of this factory create specific types of policy sources
+ * (e.g., local file, remote store, in-memory, etc.).
+ */
+export declare abstract class AuthorizationPolicySourceFactory<C extends AuthorizationPolicySourceConfig = AuthorizationPolicySourceConfig> extends AbstractResourceFactory<AuthorizationPolicySource, C> {
+    /**
+     * Creates an authorization policy source from the given configuration.
+     *
+     * @param config - Configuration for the policy source
+     * @param factoryArgs - Additional factory arguments
+     * @returns The created authorization policy source
+     */
+    abstract create(config?: C | Record<string, unknown> | null, ...factoryArgs: unknown[]): Promise<AuthorizationPolicySource>;
+    /**
+     * Static helper to create an authorization policy source using the factory registry.
+     *
+     * @param config - Configuration for the policy source
+     * @param options - Resource creation options
+     * @returns The created policy source, or undefined if no factory matched
+     */
+    static createAuthorizationPolicySource<C extends AuthorizationPolicySourceConfig = AuthorizationPolicySourceConfig>(config?: C | Record<string, unknown> | null, options?: CreateResourceOptions): Promise<AuthorizationPolicySource | undefined>;
+}

package/dist/types/naylence/fame/security/auth/policy/authorization-policy-source.d.ts

@@ -0,0 +1,20 @@
+import type { AuthorizationPolicy } from './authorization-policy.js';
+/**
+ * Interface for sources that provide authorization policies.
+ *
+ * Policy sources abstract where the policy definition comes from,
+ * allowing policies to be loaded from local files, remote stores,
+ * or other sources.
+ */
+export interface AuthorizationPolicySource {
+    /**
+     * Loads and returns the authorization policy.
+     *
+     * This method may be called multiple times, for example when
+     * reloading a policy after changes. Implementations should
+     * handle caching internally if needed.
+     *
+     * @returns The loaded authorization policy
+     */
+    loadPolicy(): Promise<AuthorizationPolicy>;
+}

package/dist/types/naylence/fame/security/auth/policy/authorization-policy.d.ts

@@ -0,0 +1,55 @@
+import type { FameDeliveryContext, FameEnvelope } from '@naylence/core';
+import type { NodeLike } from '../../../node/node-like.js';
+import type { RuleAction } from './authorization-policy-definition.js';
+/**
+ * The effect of an authorization decision.
+ */
+export type AuthorizationEffect = 'allow' | 'deny';
+/**
+ * Represents a single step in the policy evaluation process.
+ * Useful for debugging and auditing authorization decisions.
+ */
+export interface AuthorizationEvaluationStep {
+    /** Rule identifier that was evaluated */
+    ruleId: string;
+    /** Expression or condition that was evaluated */
+    expression?: string;
+    /** Result of the evaluation */
+    result: boolean;
+    /** Context values used in evaluation (for debugging) */
+    boundValues?: Record<string, unknown>;
+}
+/**
+ * The result of an authorization policy evaluation.
+ */
+export interface AuthorizationDecision {
+    /** The authorization effect: allow or deny */
+    effect: AuthorizationEffect;
+    /** Human-readable reason for the decision */
+    reason?: string;
+    /** Identifier of the rule that matched (for debugging/audit) */
+    matchedRule?: string;
+    /** Evaluation trace for detailed debugging */
+    evaluationTrace?: AuthorizationEvaluationStep[];
+}
+/**
+ * Interface for authorization policies that evaluate whether a request
+ * should be allowed or denied.
+ *
+ * The policy receives the same parameters as `Authorizer.authorize`,
+ * giving it full access to the node, envelope, and delivery context
+ * for making authorization decisions.
+ */
+export interface AuthorizationPolicy {
+    /**
+     * Evaluates an authorization request and returns a decision.
+     *
+     * @param node - The node handling the request
+     * @param envelope - The FAME envelope being authorized
+     * @param context - Optional delivery context with authorization info, origin, etc.
+     * @param action - Optional authorization action token (route-oriented: Connect,
+     *                 ForwardUpstream, ForwardDownstream, ForwardPeer, DeliverLocal, '*')
+     * @returns A decision indicating whether to allow or deny the request
+     */
+    evaluateRequest(node: NodeLike, envelope: FameEnvelope, context?: FameDeliveryContext, action?: RuleAction): Promise<AuthorizationDecision>;
+}