docs: record module authorization architecture
Adds ADR 0014 recording the durable architecture Phase 5A established across both passes: the shared contracts-layer PermissionDeclaration, manifest version 3 replacing version 2's bare permission strings, the reserved core.* namespace and the structural guarantee that a module-vs-Core collision always surfaces as ModulePermissionCompositionError rather than the generic PermissionRegistryError duplicate path, deterministic registry composition, startup ordering, repository-root/package-version resolution, registry injection into apps/api's enforcement and explicit-grant HTTP API, the static-snapshot/historical-record preservation guarantees, and Doctor/modules:validate integration. Indexes it in the ADR README, cross-references it from ADR 0006 (only its manifestVersion 2 / permission-string decision is superseded; the rest of ADR 0006 remains accepted, and its historical text is left untouched) and ADR 0013 (module permission registration, deferred there, is what ADR 0014 implements), and links it from the relevant development documentation. Corrects two comments discovered during a direct source audit that overstated where a module-vs-Core permission collision is actually caught (core/src/modules/permissions.ts, apps/api/src/platform-permissions.ts) — comment-only, no behavior change, already covered by existing tests. Also corrects a documentation claim in docs/development/authorization.md that incorrectly implied removing a module blocks explicit revocation of its historical grants; grants-routes.ts's revoke handler never consults the permission registry, so revocation remains unaffected.
This commit is contained in:
@@ -62,14 +62,16 @@ export interface ComposeStartupPermissionRegistryOptions {
|
||||
readonly modulesDirectoryOverride?: string;
|
||||
/** Test-only escape hatch: supplies an already-discovered module list directly, skipping the
|
||||
* filesystem discovery step entirely, while still running the real `composePlatformPermissionRegistry`
|
||||
* on it. Exists because a genuine exact permission-id collision between two modules — or between
|
||||
* a module and Core — is unreachable through real discovery: module ids are unique (discovery
|
||||
* itself rejects a duplicate) and every permission id is namespaced by its own module's id, so
|
||||
* no two really-discovered modules can ever contribute the same permission id. Proving
|
||||
* composition's own duplicate-rejection behavior, and that startup has created no pool before it
|
||||
* runs, requires supplying deliberately conflicting declarations directly. Never set by the
|
||||
* executable entry point; mutually exclusive with `modulesDirectoryOverride` in practice, since
|
||||
* only one discovery-bypass is ever needed for a given scenario.
|
||||
* on it. Exists because a genuine exact permission-id collision between two modules is
|
||||
* unreachable through real discovery: module ids are unique (discovery itself rejects a
|
||||
* duplicate) and every permission id is namespaced by its own module's id, so no two
|
||||
* really-discovered modules can ever contribute the same permission id. Proving
|
||||
* `PermissionRegistryError`'s own duplicate-rejection behavior in composition, and that startup
|
||||
* has created no pool before it runs, requires supplying deliberately conflicting declarations
|
||||
* directly. (A module-vs-Core collision, by contrast, *is* reachable through real discovery — a
|
||||
* module whose own id is `"core"` — and surfaces as `ModulePermissionCompositionError`, not this
|
||||
* case; `modulesDirectoryOverride` with a real fixture is what proves that one.) Never set by the
|
||||
* executable entry point.
|
||||
*/
|
||||
readonly discoveredModulesOverride?: readonly DiscoveredModule[];
|
||||
}
|
||||
|
||||
Reference in New Issue
Block a user