ARCH-02 — Project-scoped repository associations and authorized resource lookup #831

New Issue

2026-07-22T19:47:26-05:00

jcwalker3 commented

2026-07-22 19:47:26 -05:00

Candidate architecture requiring executable validation; not yet approved, production-ready, or certified.

Parents: #820, #828. Depends on: #829 (bindings), #830 (resources).

1. Summary / objective

Implement project-scoped repository associations and authorized resource lookup: authenticate the caller, check the current project→repository grant, check the current association, and return data only through the sanctioned interface.

2. Security/correctness problem

Associations must never become independent authorization: a revoked grant must immediately make an old association unreadable. On SQLite there are no table-level read privileges or SELECT triggers, so read authorization is [TRUSTED-SERVICE] and must be stated as such, not overclaimed as [SCHEMA].

3. Threat model / failure modes

Direct SELECT bypassing the service; cross-project disclosure; reading via a stale/revoked grant; reading an archived resource; spoofed actor context.

4. In-scope behavior

lookup_resource_for_project [TRUSTED-SERVICE]: authenticate caller; require an active project_repository_grants row for the resource's binding and an existing association; return only through the sanctioned interface; prohibit direct DB access by the application role.
ensure/associate authorization derives from binding-level grants (ensure = internal_service; associate_project = project.admin), never from a pre-existing association. [SCHEMA] on the write triggers.
PostgreSQL may use a properly-privileged SECURITY DEFINER function or security-barrier view; SQLite uses a service routine + [PERM] (application role has no direct DB read of these tables).
Association creation, suspension, retirement, revocation; immediate behavior after a grant/association becomes inactive (subsequent lookups fail closed).

5. Exclusions

No resource identity/refs (→ #830), no bindings (→ #829). project_repository_grants is owned by ARCH-03 (out of this program's leaves) — this issue depends on its properties (active/revoked status, (project,binding) active uniqueness, non-NULL grantor) and must declare that dependency explicitly rather than redefining it.

6. Schema/operation contracts

resource_project_associations (status lifecycle). Operations: lookup_resource_for_project, associate_project, suspend_association, retire_association, revoke_association.

7. SQLite behavior

Read authorization is a service routine; the application role has no direct read of canonical_resources/associations (filesystem/role separation). [TRUSTED-SERVICE].

8. PostgreSQL behavior

SECURITY DEFINER lookup or security-barrier view with cp_readonly restricted; privileges specified; direct SELECT by the application role denied.

9. Concurrency / transaction requirements

A lookup concurrent with grant revocation must not read through the revoked grant (recheck under snapshot); define behavior precisely.

10. Structured results

RESOURCE_RETURNED, NOT_FOUND, PROJECT_NOT_AUTHORIZED, ASSOCIATION_INACTIVE, GRANT_INACTIVE, INVALID_ACTOR_CONTEXT.

11. Enforcement classification

Write-side association/ensure authorization [SCHEMA] (triggers); read-side lookup authorization [TRUSTED-SERVICE] (SQLite) / DB-mediated via SECURITY DEFINER (PostgreSQL).

12. Acceptance criteria

Lookup requires an active grant AND an association.
A revoked grant makes an old association unreadable.
Associations never confer independent authorization.
associate_project requires an active grant; project.admin cannot write canonical_resources.
Cross-project disclosure impossible.
Direct SELECT by the application role denied (PG) / unavailable (SQLite).
Spoofed/absent context fails closed.

13. Named tests

t_lookup_requires_grant_and_assoc(+/−), t_revoked_grant_unreadable(−), t_assoc_not_authorization(−), t_associate_requires_grant(−), t_admin_cannot_write_resource(−), t_cross_project_disclosure(−), t_direct_select(−, PG), t_spoofed_context(−).

14. Audit events / evidence

resource_lookup, association_created/suspended/retired/revoked. Test output evidence.

15. Dependencies / parent

Parents #820, #828; depends #829, #830, and ARCH-03 project_repository_grants (external to this program's leaves — declared, not redefined).

16. Definition of done

Executable SQLite + PostgreSQL; ACs pass incl. direct-SELECT and spoof; bounded PR; no self-review/merge.

17. Known limitations / deferred

project_repository_grants semantics are assumed from ARCH-03; if ARCH-03 is unavailable, a minimal grant table stub with the required properties must be created as a linked follow-up rather than folding grant semantics into this issue.

**Candidate architecture requiring executable validation; not yet approved, production-ready, or certified.** Parents: #820, #828. Depends on: #829 (bindings), #830 (resources). ## 1. Summary / objective Implement project-scoped repository associations and authorized resource lookup: authenticate the caller, check the current project→repository grant, check the current association, and return data only through the sanctioned interface. ## 2. Security/correctness problem Associations must never become independent authorization: a revoked grant must immediately make an old association unreadable. On SQLite there are no table-level read privileges or SELECT triggers, so read authorization is `[TRUSTED-SERVICE]` and must be stated as such, not overclaimed as `[SCHEMA]`. ## 3. Threat model / failure modes Direct `SELECT` bypassing the service; cross-project disclosure; reading via a stale/revoked grant; reading an archived resource; spoofed actor context. ## 4. In-scope behavior - `lookup_resource_for_project` `[TRUSTED-SERVICE]`: authenticate caller; require an **active** `project_repository_grants` row for the resource's binding **and** an existing association; return only through the sanctioned interface; prohibit direct DB access by the application role. - `ensure`/`associate` authorization derives from binding-level grants (`ensure` = internal_service; `associate_project` = project.admin), never from a pre-existing association. `[SCHEMA]` on the write triggers. - PostgreSQL may use a properly-privileged SECURITY DEFINER function or security-barrier view; SQLite uses a service routine + `[PERM]` (application role has no direct DB read of these tables). - Association creation, suspension, retirement, revocation; immediate behavior after a grant/association becomes inactive (subsequent lookups fail closed). ## 5. Exclusions No resource identity/refs (→ #830), no bindings (→ #829). `project_repository_grants` is owned by ARCH-03 (out of this program's leaves) — this issue depends on its properties (active/revoked status, `(project,binding)` active uniqueness, non-NULL grantor) and must declare that dependency explicitly rather than redefining it. ## 6. Schema/operation contracts `resource_project_associations` (status lifecycle). Operations: `lookup_resource_for_project`, `associate_project`, `suspend_association`, `retire_association`, `revoke_association`. ## 7. SQLite behavior Read authorization is a service routine; the application role has no direct read of `canonical_resources`/associations (filesystem/role separation). `[TRUSTED-SERVICE]`. ## 8. PostgreSQL behavior SECURITY DEFINER lookup or security-barrier view with `cp_readonly` restricted; privileges specified; direct SELECT by the application role denied. ## 9. Concurrency / transaction requirements A lookup concurrent with grant revocation must not read through the revoked grant (recheck under snapshot); define behavior precisely. ## 10. Structured results `RESOURCE_RETURNED`, `NOT_FOUND`, `PROJECT_NOT_AUTHORIZED`, `ASSOCIATION_INACTIVE`, `GRANT_INACTIVE`, `INVALID_ACTOR_CONTEXT`. ## 11. Enforcement classification Write-side association/ensure authorization `[SCHEMA]` (triggers); read-side lookup authorization `[TRUSTED-SERVICE]` (SQLite) / DB-mediated via SECURITY DEFINER (PostgreSQL). ## 12. Acceptance criteria 1. Lookup requires an active grant AND an association. 2. A revoked grant makes an old association unreadable. 3. Associations never confer independent authorization. 4. `associate_project` requires an active grant; project.admin cannot write `canonical_resources`. 5. Cross-project disclosure impossible. 6. Direct `SELECT` by the application role denied (PG) / unavailable (SQLite). 7. Spoofed/absent context fails closed. ## 13. Named tests `t_lookup_requires_grant_and_assoc`(+/−), `t_revoked_grant_unreadable`(−), `t_assoc_not_authorization`(−), `t_associate_requires_grant`(−), `t_admin_cannot_write_resource`(−), `t_cross_project_disclosure`(−), `t_direct_select`(−, PG), `t_spoofed_context`(−). ## 14. Audit events / evidence `resource_lookup`, `association_created/suspended/retired/revoked`. Test output evidence. ## 15. Dependencies / parent Parents #820, #828; depends #829, #830, and ARCH-03 `project_repository_grants` (external to this program's leaves — declared, not redefined). ## 16. Definition of done Executable SQLite + PostgreSQL; ACs pass incl. direct-SELECT and spoof; bounded PR; no self-review/merge. ## 17. Known limitations / deferred `project_repository_grants` semantics are assumed from ARCH-03; if ARCH-03 is unavailable, a minimal grant table stub with the required properties must be created as a linked follow-up rather than folding grant semantics into this issue.

jcwalker3 referenced this issue

2026-07-22 19:51:24 -05:00

Architecture acceptance matrix — invariant, test, evidence, and backend traceability #837

jcwalker3 referenced this issue

2026-07-22 20:04:09 -05:00

Architecture program — role-delivery-reliability control plane #820

jcwalker3 referenced this issue

2026-07-22 20:12:12 -05:00

ARCH-02 — Canonical repository resources, transport identity, and authorized lookup #828

jcwalker3 added the security architecture status:blocked type:feature workflow-hardening control-plane database labels 2026-07-22 20:17:05 -05:00

Sign in to join this conversation.

Branches Tags

master

fix/issue-987-native-mcp-bootstrap

feat/issue-985-project-scoped-launcher-identity

fix/issue-983-cross-repo-base-ref

feat/issue-980-stale-worker-retirement

fix/issue-975-client-identity-heartbeat

fix/issue-973-cross-repo-canonical-roots

fix/issue-970-safely-resolve-missing-worktrees

fix/issue-969-native-mcp-bootstrap

feat/issue-664-break-glass-restart

feat/issue-708-mcp-namespace-attachment

feat/issue-665-restart-audit

fix/issue-700-durable-walls

fix/issue-704-prevent-env-workspace-bindings

feat/issue-707-cross-project-boundaries

fix/issue-690-review-profile-switch-guard

fix/issue-953-bootstrap-lock-provenance

feat/issue-949-native-fleet-inventory

fix/issue-943-runtime-context-helpers

fix/issue-945-owning-pr-renewal-evidence

fix/issue-941-scope-guard-bootstrap-wiring

docs/issue-930-remote-mcp-coupling-inventory

fix/issue-892-author-bootstrap-deadlock

fix/issue-686-detect-reject-manual-mcp

fix/issue-672-mcp-config-drift

fix/issue-689-deterministic-mcp-namespace

feat/issue-666-concurrent-mcp-restart-tests

feat/issue-659-maintenance-drain-mode

feat/issue-648-notifications-console

fix/issue-670-direct-master-incident

feat/issue-644-console-recovery

feat/issue-650-providers-insights

feat/issue-669-scoped-component-recovery

docs/issue-668-mcp-ha-rolling-restart

feat/issue-667-console-restart-controls

feat/issue-645-linkage-console

feat/issue-643-request-preview-initiate

fix/issue-897-permission-stale-runtime-classification

feat/issue-641-runtime-session-view

feat/issue-663-restart-classes

feat/issue-661-drain-proof-hard-gate

fix/issue-854-semantic-container-exclusion

issue-640

fix/issue-682-starlette-httpx2

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: Scaled-Tech-Consulting/Gitea-Tools#831