Generated Action Protection¶

This document states what protects a generated module action at runtime, and the rule the Factory SecurityReadiness workflow uses to report an action that nothing protects.

The scanner reads declared contracts and module code only. It never invents a permission grant, and it does not infer intent from action or module names. A finding means the bundle's own contracts leave a caller able to do more than the app declares, or the scanner cannot show that they do not.

What Protects An Action¶

Five declared contracts decide who can run a module action:

A host runs without authentication only in local development, test, or an unconfigured environment. Without authentication the caller's identity is not verified, module dispatch skips permission and entitlement checks, and ownership cannot separate callers. The scanner reads the bundle, not the deployment: rows 5 to 10 below assume a host that authenticates callers.

What An Action Reaches¶

Runtime persistence does not bind an app module to its own collections, so an action's reach is every collection its module can address:

• the collections data/contract.json declares under the module's surface;
• collections a shared_collections entry shares with the module in shared_with or read_by;
• every collection the module's code addresses: ctx.persistence.collection(module_id, name) for any module, ctx.persistence.literal_collection(name), and app_data_from_context(ctx).collection(alias) resolved through the contract's aliases;
• the same, for code the module imports from another module or from elsewhere in the app, including by the package name the runtime gives each module's code.

With a data contract present, collection() refuses a module and name pair that the contract does not declare, and a literal or alias name cannot address a collection that is owned per user or per workspace. A literal or alias name can address any other collection, declared in the contract or not. An app without a data contract has no scoped collection, and an app whose contract the runtime refuses does not load; the scanner treats both as unscoped reach.

The scanner reads every Python file under the module's directory, and the app files that code imports, with AppGenerator's persistence resolver. It proves reach only from forms it recognises:

• the persistence calls above, with arguments it reads as string constants. A constant counts only if no app file may set an attribute of that name. Any other argument stands for every collection the contract lets that call reach;
• persistence handles followed through assignments, helper functions that return them, and attribute names drawn from known strings.

Anything else that could reach records makes the module's reach unscoped (row 9):

• a persistence handle passed to another function, kept in a container, or used outside its API;
• reflection over objects, namespaces or frames, and module state set at run time;
• code imported by a name chosen at run time, loaded through the import system, compiled, or run in another process;
• a database driver or the runtime's raw client internals, in any file the module's code follows;
• code the AppGenerator persistence guard rejects;
• code too large or too deeply nested to read within the reading's bounds.

The reading is static and bounded, not a sandbox. It follows the code a module imports, not objects handed to that code at run time, and it does not read dependencies outside the app bundle. A module without findings has no unprotected reach the scanner could read. That is not proof that it has none.

Decision Table¶

Each row is an action with the declared contracts on the left. "Another user's records" means records another signed-in user created. "Reaches" means the module's reach, as defined above.

Row 9 covers an app without a valid data contract, a collection that declares neither scoped ownership with an owner field nor app_wide tenancy, a literal or alias name of a collection the contract does not declare, and reach the scanner cannot resolve.

A restricting gate is an entitlement_gate whose capability a valid config/subscriptions.yaml does not grant through its default plan (the default_plan_id of a v1 contract, or any product's default plan in v2). A gate the default plan grants admits every signed-in user, so it counts as no gate. The scanner reads the plan catalog, not assignments: an app-level assignment grants its plan to every caller, and then a gate that plan covers restricts no one.

Severity follows what the caller can do. High means any signed-in user, or any caller, can act on records that are not theirs or that nothing declares an owner for. Medium means the declared contracts bound who calls the action but not whose records it changes: the gate restricts by plan only (row 7), or nothing declares what the action reaches (row 10).

The Scanner Rule¶

The scanner reads only the app root the runtime binds: app/ when it holds app.json and the bundle root does not, otherwise the bundle root. Files outside that root are never loaded.

module_permissions:missing:{module_id}:{action_id} is reported for an action with no permissions, unless one of these holds:

• its surface is exactly public or public_readonly;
• its surface is exactly internal with an explicit permissions: [];
• its surface is absent or null, the app declares sign-in, and either everything its module reaches is owned (row 6), or its module reaches no collection and its entitlement_gate is a restricting gate.

Every other surface value, including admin_internal, public_mutation, a blank or padded value, and a permissions value that is not a list, still needs a declared permission; the loader rejects the malformed ones, and the scanner reports them rather than pass a bundle that cannot run. module_permissions:undeclared separately reports permission ids that module.yaml does not declare. Findings remain advisory, as factory_app/build_context/SecurityReadiness/baseline_security_controls.yaml states, and that file's module_permissions_declared check carries this rule.

Evidence¶

tests/test_security_readiness_action_protection.py builds variants of the recorded fdfa818e bundle. Most change one declared contract; some change several, add a module, or change module code. Scanner tests assert the findings and severities of every variant, including malformed contracts, which return findings rather than fail. Tests of the code reading assert which persistence uses it resolves and which forms it reports as unresolved.

Eight tests compose a variant's module router and executor against a real MongoDB and dispatch actions as anonymous and signed-in callers. Signed-in principals are injected through the optional_user dependency rather than validated from tokens. They cover rows 2, 5, 6 (per user, per workspace and a paid owner-scoped summary), 7, 8 and 10, reach into another module's collection, and row 4 on a host without authentication, where every caller shares one identity. Every dispatched variant loads without a failed module. Row 3 is covered by tests/test_admin_module_dispatch.py. Row 1 and row 9 are asserted by the scanner tests only.

Related Docs¶

• Tenant Auth And Scope
• Module System
• Data Contracts
• Data Contract And Revision Contract