@naylence/runtime 0.3.21 → 0.4.0

package/dist/esm/naylence/fame/security/auth/default-policy-authorizer.js

@@ -0,0 +1,287 @@
+import { createAuthorizationContext } from '@naylence/core';
+import { getLogger } from '../../util/logging.js';
+const logger = getLogger('naylence.fame.security.auth.default_policy_authorizer');
+function decodeCredentials(credentials) {
+    if (typeof TextDecoder !== 'undefined') {
+        return new TextDecoder().decode(credentials);
+    }
+    if (typeof Buffer !== 'undefined') {
+        return Buffer.from(credentials).toString('utf-8');
+    }
+    throw new Error('Unable to decode credential bytes without TextDecoder support');
+}
+function normalizeToken(credentials) {
+    const raw = typeof credentials === 'string'
+        ? credentials
+        : decodeCredentials(credentials);
+    const trimmed = raw.trim();
+    if (trimmed.length === 0) {
+        return undefined;
+    }
+    if (trimmed.toLowerCase().startsWith('bearer ')) {
+        const candidate = trimmed.slice(7).trim();
+        return candidate.length > 0 ? candidate : undefined;
+    }
+    return trimmed;
+}
+function normalizeOptions(options) {
+    if (options === undefined || options === null) {
+        return {};
+    }
+    if (typeof options !== 'object') {
+        throw new TypeError('DefaultPolicyAuthorizer options must be an object');
+    }
+    const candidate = options;
+    return {
+        tokenVerifier: candidate.tokenVerifier ?? candidate.token_verifier,
+        policy: candidate.policy,
+        policySource: candidate.policySource ?? candidate.policy_source,
+    };
+}
+/**
+ * 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 class DefaultPolicyAuthorizer {
+    constructor(options = {}) {
+        this.policyLoaded = false;
+        const normalized = normalizeOptions(options);
+        if (normalized.tokenVerifier) {
+            this.tokenVerifierImpl = normalized.tokenVerifier;
+        }
+        if (normalized.policy) {
+            this.policyImpl = normalized.policy;
+            this.policyLoaded = true;
+        }
+        if (normalized.policySource) {
+            this.policySource = normalized.policySource;
+        }
+        // Validate that we have either a policy or a policy source
+        if (!normalized.policy && !normalized.policySource) {
+            throw new Error('DefaultPolicyAuthorizer requires either a policy or a policySource');
+        }
+    }
+    /**
+     * The currently active authorization policy.
+     */
+    get policy() {
+        if (!this.policyImpl) {
+            throw new Error('Authorization policy not loaded. Call ensurePolicyLoaded() first.');
+        }
+        return this.policyImpl;
+    }
+    /**
+     * The token verifier used for authentication.
+     */
+    get tokenVerifier() {
+        if (!this.tokenVerifierImpl) {
+            throw new Error('DefaultPolicyAuthorizer is not initialized properly, missing tokenVerifier');
+        }
+        return this.tokenVerifierImpl;
+    }
+    set tokenVerifier(verifier) {
+        this.tokenVerifierImpl = verifier;
+    }
+    /**
+     * Ensures the authorization policy is loaded.
+     * If using a policy source, loads the policy from it.
+     */
+    async ensurePolicyLoaded() {
+        if (this.policyLoaded && this.policyImpl) {
+            return;
+        }
+        if (!this.policySource) {
+            throw new Error('No policy source configured and no policy provided');
+        }
+        logger.debug('loading_policy_from_source');
+        this.policyImpl = await this.policySource.loadPolicy();
+        this.policyLoaded = true;
+        logger.info('policy_loaded_from_source');
+    }
+    /**
+     * Reloads the authorization policy from the policy source.
+     * Only works if a policy source was configured.
+     */
+    async reloadPolicy() {
+        if (!this.policySource) {
+            throw new Error('Cannot reload policy: no policy source configured');
+        }
+        logger.debug('reloading_policy_from_source');
+        this.policyImpl = await this.policySource.loadPolicy();
+        this.policyLoaded = true;
+        logger.info('policy_reloaded_from_source');
+    }
+    /**
+     * 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
+     */
+    async authenticate(credentials) {
+        const token = normalizeToken(credentials);
+        if (!token) {
+            return undefined;
+        }
+        try {
+            const verifier = this.tokenVerifier;
+            const context = await verifier.verify(token);
+            return createAuthorizationContext({
+                ...context,
+                authenticated: true,
+                authorized: false, // Authorization happens in authorize()
+                authMethod: context.authMethod ?? 'jwt',
+            });
+        }
+        catch (error) {
+            logger.warning('token_verification_failed', {
+                error: error instanceof Error ? error.message : String(error),
+            });
+            return 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
+     */
+    async authorize(node, envelope, context) {
+        const authorization = context?.security?.authorization;
+        // Must be authenticated first
+        if (!authorization || !authorization.authenticated) {
+            logger.debug('authorization_denied_not_authenticated');
+            return undefined;
+        }
+        // Ensure policy is loaded
+        await this.ensurePolicyLoaded();
+        // For NodeAttach frames, evaluate policy with 'Connect' action
+        const frameType = envelope.frame?.type;
+        if (frameType === 'NodeAttach') {
+            let decision;
+            try {
+                decision = await this.policy.evaluateRequest(node, envelope, context, 'Connect');
+            }
+            catch (error) {
+                logger.error('policy_evaluation_failed', {
+                    error: error instanceof Error ? error.message : String(error),
+                    action: 'Connect',
+                });
+                return undefined;
+            }
+            if (decision.effect === 'allow') {
+                logger.debug('authorization_allowed', {
+                    matchedRule: decision.matchedRule,
+                    reason: decision.reason,
+                    action: 'Connect',
+                });
+                return createAuthorizationContext({
+                    ...authorization,
+                    authorized: true,
+                    authMethod: authorization.authMethod ?? 'policy',
+                });
+            }
+            else {
+                logger.debug('authorization_denied', {
+                    matchedRule: decision.matchedRule,
+                    reason: decision.reason,
+                    action: 'Connect',
+                });
+                return undefined;
+            }
+        }
+        // For non-NodeAttach frames, authentication is sufficient at this stage.
+        // Route-level authorization is performed via authorizeRoute() after
+        // the routing decision is made.
+        logger.debug('authorization_passed_authentication_only', {
+            envp_id: envelope.id,
+            frame_type: frameType,
+        });
+        return createAuthorizationContext({
+            ...authorization,
+            authorized: true,
+            authMethod: authorization.authMethod ?? 'policy',
+        });
+    }
+    /**
+     * 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
+     */
+    async authorizeRoute(node, envelope, action, context) {
+        const authorization = context?.security?.authorization;
+        // If not authenticated, deny route authorization
+        if (!authorization || !authorization.authenticated) {
+            logger.debug('route_authorization_denied_not_authenticated', {
+                action,
+            });
+            return {
+                authorized: false,
+                denialReason: 'not_authenticated',
+            };
+        }
+        // Ensure policy is loaded
+        await this.ensurePolicyLoaded();
+        // Evaluate the policy with the provided action
+        let decision;
+        try {
+            decision = await this.policy.evaluateRequest(node, envelope, context, action);
+        }
+        catch (error) {
+            logger.error('route_policy_evaluation_failed', {
+                error: error instanceof Error ? error.message : String(error),
+                action,
+            });
+            return {
+                authorized: false,
+                denialReason: 'policy_evaluation_error',
+            };
+        }
+        if (decision.effect === 'allow') {
+            logger.debug('route_authorization_allowed', {
+                matchedRule: decision.matchedRule,
+                reason: decision.reason,
+                action,
+            });
+            return {
+                authorized: true,
+                authContext: createAuthorizationContext({
+                    ...authorization,
+                    authorized: true,
+                    authMethod: authorization.authMethod ?? 'policy',
+                }),
+                matchedRule: decision.matchedRule,
+            };
+        }
+        else {
+            logger.debug('route_authorization_denied', {
+                matchedRule: decision.matchedRule,
+                reason: decision.reason,
+                action,
+            });
+            return {
+                authorized: false,
+                denialReason: decision.reason ?? 'policy_denied',
+                matchedRule: decision.matchedRule,
+            };
+        }
+    }
+}

package/dist/esm/naylence/fame/security/auth/oauth2-authorizer-factory.js

@@ -51,6 +51,7 @@ export class OAuth2AuthorizerFactory extends AuthorizerFactory {
             maxTtlSec: normalized.maxTtlSec,
             reverseAuthTtlSec: normalized.reverseAuthTtlSec,
             enforceTokenSubjectNodeIdentity: normalized.enforceTokenSubjectNodeIdentity,
+            trustedClientScope: normalized.trustedClientScope,
         };
         if (tokenIssuer) {
             authorizerOptions.tokenIssuer = tokenIssuer;
@@ -120,6 +121,11 @@ function normalizeConfig(config) {
             : DEFAULT_REVERSE_AUTH_TTL_SEC;
     const enforceTokenSubjectNodeIdentity = normalizeBooleanOption(source.enforceTokenSubjectNodeIdentity ??
         source.enforce_token_subject_node_identity, false);
+    const trustedClientScope = typeof source.trustedClientScope === 'string'
+        ? source.trustedClientScope
+        : typeof source.trusted_client_scope === 'string'
+            ? source.trusted_client_scope
+            : undefined;
     const tokenVerifierConfigInput = source.tokenVerifierConfig ?? source.token_verifier_config ?? null;
     const tokenVerifierConfig = normalizeTokenVerifierConfig({
         config: tokenVerifierConfigInput,
@@ -140,6 +146,7 @@ function normalizeConfig(config) {
         reverseAuthTtlSec: reverseAuthCandidate,
         enforceTokenSubjectNodeIdentity,
         ...(audience ? { audience } : {}),
+        ...(trustedClientScope ? { trustedClientScope } : {}),
     };
     if (tokenIssuerConfig) {
         normalized.tokenIssuerConfig = tokenIssuerConfig;

package/dist/esm/naylence/fame/security/auth/oauth2-authorizer.js

@@ -38,6 +38,10 @@ function normalizeOptions(raw) {
         (typeof snake.enforce_token_subject_node_identity === 'boolean'
             ? snake.enforce_token_subject_node_identity
             : undefined);
+    const trustedClientScope = camel.trustedClientScope ??
+        (typeof snake.trusted_client_scope === 'string'
+            ? snake.trusted_client_scope
+            : undefined);
     return {
         tokenVerifier,
         tokenIssuer,
@@ -48,6 +52,7 @@ function normalizeOptions(raw) {
         maxTtlSec,
         reverseAuthTtlSec,
         enforceTokenSubjectNodeIdentity,
+        trustedClientScope,
     };
 }
 export class OAuth2Authorizer {
@@ -63,6 +68,7 @@ export class OAuth2Authorizer {
             options.reverseAuthTtlSec ?? DEFAULT_REVERSE_AUTH_TTL_SEC;
         this.enforceTokenSubjectNodeIdentity =
             options.enforceTokenSubjectNodeIdentity ?? false;
+        this.trustedClientScope = options.trustedClientScope ?? 'node.trusted';
     }
     get tokenVerifier() {
         return this.tokenVerifierImpl;
@@ -192,11 +198,20 @@ export class OAuth2Authorizer {
             });
             return undefined;
         }
-        // Enforce token subject node identity if enabled
+        // Enforce token subject node identity if enabled and not a trusted client
         if (this.enforceTokenSubjectNodeIdentity) {
-            const validationResult = await this.validateTokenSubjectNodeIdentity(frame.systemId, claims);
-            if (!validationResult) {
-                return undefined;
+            const isTrustedClient = scopes.has(this.trustedClientScope);
+            if (isTrustedClient) {
+                logger.debug('oauth2_attach_trusted_client_bypass', {
+                    system_id: frame.systemId,
+                    trusted_scope: this.trustedClientScope,
+                });
+            }
+            else {
+                const validationResult = await this.validateTokenSubjectNodeIdentity(frame.systemId, claims);
+                if (!validationResult) {
+                    return undefined;
+                }
             }
         }
         claims.instance_id = claims.instance_id ?? frame.instanceId;

package/dist/esm/naylence/fame/security/auth/policy/authorization-policy-definition.js

@@ -0,0 +1,57 @@
+/**
+ * Authorization policy definition types.
+ *
+ * This module defines the schema for authorization policies that can be
+ * loaded from YAML/JSON files and evaluated at runtime.
+ */
+/**
+ * Maximum nesting depth for scope requirements.
+ */
+export const MAX_SCOPE_NESTING_DEPTH = 5;
+/**
+ * Known fields in AuthorizationPolicyDefinition.
+ */
+export const KNOWN_POLICY_FIELDS = new Set([
+    'version',
+    'default_effect',
+    'rules',
+]);
+/**
+ * Known fields in AuthorizationRuleDefinition.
+ * Fields not in this set trigger a warning.
+ */
+export const KNOWN_RULE_FIELDS = new Set([
+    'id',
+    'description',
+    'effect',
+    'action',
+    'address',
+    'frame_type',
+    'origin_type',
+    'scope',
+    'when', // Reserved for advanced-security
+]);
+/**
+ * Valid action values.
+ */
+export const VALID_ACTIONS = [
+    'Connect',
+    'ForwardUpstream',
+    'ForwardDownstream',
+    'ForwardPeer',
+    'DeliverLocal',
+    '*',
+];
+/**
+ * Valid origin type values (lowercase, matching DeliveryOriginType string values).
+ */
+export const VALID_ORIGIN_TYPES = [
+    'downstream',
+    'upstream',
+    'peer',
+    'local',
+];
+/**
+ * Valid effect values.
+ */
+export const VALID_EFFECTS = ['allow', 'deny'];

package/dist/esm/naylence/fame/security/auth/policy/authorization-policy-factory.js

@@ -0,0 +1,31 @@
+import { AbstractResourceFactory, createDefaultResource, createResource, } from '@naylence/factory';
+/**
+ * Base type identifier for authorization policy factories.
+ */
+export const AUTHORIZATION_POLICY_FACTORY_BASE_TYPE = 'AuthorizationPolicyFactory';
+/**
+ * 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 class AuthorizationPolicyFactory extends AbstractResourceFactory {
+    /**
+     * 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 async createAuthorizationPolicy(config, options = {}) {
+        if (config) {
+            const policy = await createResource(AUTHORIZATION_POLICY_FACTORY_BASE_TYPE, config, options);
+            if (!policy) {
+                throw new Error('Failed to create authorization policy from configuration');
+            }
+            return policy;
+        }
+        const policy = await createDefaultResource(AUTHORIZATION_POLICY_FACTORY_BASE_TYPE, null, options);
+        return policy ?? undefined;
+    }
+}

package/dist/esm/naylence/fame/security/auth/policy/authorization-policy-source-factory.js

@@ -0,0 +1,31 @@
+import { AbstractResourceFactory, createDefaultResource, createResource, } from '@naylence/factory';
+/**
+ * Base type identifier for authorization policy source factories.
+ */
+export const AUTHORIZATION_POLICY_SOURCE_FACTORY_BASE_TYPE = 'AuthorizationPolicySourceFactory';
+/**
+ * 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 class AuthorizationPolicySourceFactory extends AbstractResourceFactory {
+    /**
+     * 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 async createAuthorizationPolicySource(config, options = {}) {
+        if (config) {
+            const source = await createResource(AUTHORIZATION_POLICY_SOURCE_FACTORY_BASE_TYPE, config, options);
+            if (!source) {
+                throw new Error('Failed to create authorization policy source from configuration');
+            }
+            return source;
+        }
+        const source = await createDefaultResource(AUTHORIZATION_POLICY_SOURCE_FACTORY_BASE_TYPE, null, options);
+        return source ?? undefined;
+    }
+}

package/dist/esm/naylence/fame/security/auth/policy/authorization-policy-source.js

@@ -0,0 +1 @@
+export {};

package/dist/esm/naylence/fame/security/auth/policy/authorization-policy.js

@@ -0,0 +1 @@
+export {};

package/dist/esm/naylence/fame/security/auth/policy/basic-authorization-policy-factory.js

@@ -0,0 +1,62 @@
+/**
+ * Factory for creating BasicAuthorizationPolicy instances.
+ */
+import { AUTHORIZATION_POLICY_FACTORY_BASE_TYPE, AuthorizationPolicyFactory, } from './authorization-policy-factory.js';
+/**
+ * Lazy import for tree-shaking.
+ */
+async function safeImportModule() {
+    return await import('./basic-authorization-policy.js');
+}
+function normalizeConfig(config) {
+    if (!config) {
+        throw new Error('BasicAuthorizationPolicyFactory requires a configuration with a policyDefinition');
+    }
+    const candidate = config;
+    // Support both camelCase and snake_case for policyDefinition
+    const policyDefinition = (candidate.policyDefinition ??
+        candidate.policy_definition);
+    if (!policyDefinition || typeof policyDefinition !== 'object') {
+        throw new Error('BasicAuthorizationPolicyConfig requires a policyDefinition object');
+    }
+    // Support both camelCase and snake_case for warnOnUnknownFields
+    const warnOnUnknownFields = candidate.warnOnUnknownFields ?? candidate.warn_on_unknown_fields;
+    if (warnOnUnknownFields !== undefined && typeof warnOnUnknownFields !== 'boolean') {
+        throw new Error('warnOnUnknownFields must be a boolean');
+    }
+    return {
+        policyDefinition,
+        warnOnUnknownFields: warnOnUnknownFields ?? true,
+    };
+}
+/**
+ * Factory metadata for registration.
+ */
+export const FACTORY_META = {
+    base: AUTHORIZATION_POLICY_FACTORY_BASE_TYPE,
+    key: 'BasicAuthorizationPolicy',
+};
+/**
+ * Factory for creating BasicAuthorizationPolicy instances.
+ */
+export class BasicAuthorizationPolicyFactory extends AuthorizationPolicyFactory {
+    constructor() {
+        super(...arguments);
+        this.type = 'BasicAuthorizationPolicy';
+    }
+    /**
+     * Creates a BasicAuthorizationPolicy from the given configuration.
+     *
+     * @param config - Configuration with policyDefinition
+     * @returns The created authorization policy
+     */
+    async create(config) {
+        const normalized = normalizeConfig(config);
+        const { BasicAuthorizationPolicy } = await safeImportModule();
+        return new BasicAuthorizationPolicy({
+            policyDefinition: normalized.policyDefinition,
+            warnOnUnknownFields: normalized.warnOnUnknownFields,
+        });
+    }
+}
+export default BasicAuthorizationPolicyFactory;