diff --git a/AGENTS.md b/AGENTS.md index 05e5735..e82a10a 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -10,7 +10,8 @@ Reason in English. Communicate with humans in Chinese. Call the user “Sir”. - Cross-unit contracts and topology: `docs/_shared/20-product-tdd/` - Expensive core-py internal design: `docs/30-unit-tdd/` - Runtime, packaging, migration, observability, and recovery: `docs/40-deployment/` -- Vulnerability reporting: `SECURITY.md`; local security boundaries: `docs/30-unit-tdd/security-model.md` +- Shared security model: `docs/_shared/20-product-tdd/security-boundary-model.md`; vulnerability reporting: `SECURITY.md`; + core runtime realization: `docs/30-unit-tdd/security-model.md` - Volatile task control: `tasks/`; never treat it as durable truth, but retain an active packet until its parent task closes - Mechanically enforceable facts: code, configuration, schemas, tests, assertions, lint, and CI - Repeated subtree hazards only: the nearest local `AGENTS.md` @@ -27,7 +28,8 @@ Resolve the semantic owner before adding durable material. A Unit is a logical r - Before promoting behavior, evaluate delivery owner, durable owner, interface layer, and external capability owner independently. Importance, first-party distribution, current pressure, or successful acceptance on one axis does not prove another. - Before owning external protocol mechanics, inspect existing dependencies and primary documentation and name the unsupported gap. Keep only the application-specific remainder. - Read the nearest local `AGENTS.md` before changing its subtree. Read shared Product or Product TDD only when that owner is implicated, then the relevant local Unit TDD or Deployment document. -- Before a security-sensitive claim, read the security model and name actor, capability, asset, boundary, harm, and attack path. Missing defense in depth is hardening unless evidence shows a boundary violation. +- Before a security-sensitive claim，read the shared security model and relevant local realization；name actor，capability， + asset，boundary，harm and attack path。Missing defense in depth is hardening unless evidence shows a boundary violation。 - Exclude `tasks/`, generated output, dependencies, environments, caches, and temporary directories from ordinary source and durable-doc search unless they are the evidence target. - Clean task artifacts by parent-task lifecycle, not directory class, age, size, or completed child units. Splitting content must not create a second control authority. - Use sub-agents only when bounded isolation or parallel capacity repays assignment, validation, integration, conflict, and residual cost. Primary owns the Human relationship, global integration, and material residual. diff --git a/README.md b/README.md index 3df8d32..d133685 100644 --- a/README.md +++ b/README.md @@ -32,10 +32,11 @@ Exact onboarding steps, runtime limits, and cleanup: ## Security -Report vulnerabilities privately through [SECURITY.md](SECURITY.md). Security-sensitive -design and triage should use the repository's [Core Security -Model](docs/30-unit-tdd/security-model.md) rather than treating hardening practices as -context-free requirements. +Report vulnerabilities privately through [SECURITY.md](SECURITY.md). Security-sensitive design and +triage use the shared [Security Boundary +Model](docs/_shared/20-product-tdd/security-boundary-model.md) and core-py's local [runtime +projection](docs/30-unit-tdd/security-model.md)，rather than treating hardening practices as +context-free requirements。 ## Documentation Map @@ -50,7 +51,7 @@ If `docs/_shared/` is missing, run `git submodule update --init --recursive` bef - Shared product truth: [docs/_shared/10-prd/index.md](docs/_shared/10-prd/index.md) - Shared product glossary: [docs/_shared/10-prd/glossary.md](docs/_shared/10-prd/glossary.md) - Shared cross-unit technical truth: [docs/_shared/20-product-tdd/](docs/_shared/20-product-tdd/) -- Local unit design and security model: [docs/30-unit-tdd/README.md](docs/30-unit-tdd/README.md) +- Local unit design and runtime security boundaries: [docs/30-unit-tdd/README.md](docs/30-unit-tdd/README.md) - Deployment and runtime truth: [docs/40-deployment/README.md](docs/40-deployment/README.md) - Agent-owned volatile task workspaces: [tasks/](tasks/) diff --git a/SECURITY.md b/SECURITY.md index e0b669d..8174bcb 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -42,9 +42,10 @@ private collaboration and coordinated publication. ## Security Model -The [Core Security Model](docs/30-unit-tdd/security-model.md) defines this repository's -actors, assets, trust boundaries, valid security harms, non-boundaries, and proportionality -method. It is the starting point for security-sensitive design and triage; implementation, -tests, CI, and deployment contracts remain authoritative for the controls they enforce. +The shared [Security Boundary +Model](docs/_shared/20-product-tdd/security-boundary-model.md) defines project-wide actors， +assets，trust boundaries and proportional classification。The local [Core Runtime Security +Boundaries](docs/30-unit-tdd/security-model.md) maps that model to this repository；implementation， +tests，CI and deployment contracts remain authoritative for the controls they enforce。 [report]: https://github.com/InKCre/core-py/security/advisories/new diff --git a/docs/30-unit-tdd/README.md b/docs/30-unit-tdd/README.md index 07be03a..0709673 100644 --- a/docs/30-unit-tdd/README.md +++ b/docs/30-unit-tdd/README.md @@ -11,6 +11,6 @@ This directory owns expensive internal design truth for logical units delivered | [mail-extension.md](mail-extension.md) | Mail identity, MIME materialization, collection, graph, and failure boundaries | | [memos-extension.md](memos-extension.md) | Memos adapter identity, graph grammar, persistence, and failure boundaries | | [rss-extension.md](rss-extension.md) | RSS adapter identity, collection lifecycle, reconciliation, and materialization | -| [security-model.md](security-model.md) | Core-py actors, assets, trust boundaries, security harms, and proportionality | +| [security-model.md](security-model.md) | Core-py realization of the shared security boundary model | Do not add a document for a directory inventory, a fact cheaply recovered from code, a one-off decision, or a cross-unit contract already owned by `../_shared/20-product-tdd/`. Put repeated physical-subtree hazards in the nearest `AGENTS.md`; put runtime, rollout, recovery, and environment truth in `../40-deployment/`. diff --git a/docs/30-unit-tdd/security-model.md b/docs/30-unit-tdd/security-model.md index f8c3251..6890448 100644 --- a/docs/30-unit-tdd/security-model.md +++ b/docs/30-unit-tdd/security-model.md @@ -1,217 +1,85 @@ -# Core Security Model - -## Purpose - -This document defines the repository-local security model for `core-py`. It helps humans -and agents decide whether an observation is a vulnerability, an ordinary bug, a hardening -opportunity, an operational risk, or an accepted risk. - -Read it before making a security-sensitive design or triage claim. It is not a list of -controls to maximize. A proposed control is justified only when it protects an identified -asset from a plausible actor crossing an intended trust boundary at a proportionate cost. - -External vulnerability reporting is owned by the root [Security Policy](../../SECURITY.md). -Exact authentication, database, and runtime behavior remains owned by code, tests, CI, and -the linked deployment contracts. - -## Scope - -The model covers the FastAPI runtime, the executable PostgreSQL contract, built-in -extensions, source collection, resolver/storage access, background jobs, and the artifact -and deployment surfaces owned by this repository. - -It does not define browser rendering safety, native-client storage, organization-wide -account security, or a product-wide disclosure policy for other InKCre repositories. -Cross-repository security assumptions belong in the shared Hub when they become stable -product contracts. - -## System And Trust Boundaries - -```mermaid -flowchart LR - owner["Deployment owner"] -->|"operates and configures"| runtime["Core runtime"] - peer["Admitted peer client"] -->|"peer JWT"| runtime - caller["Untrusted network caller"] -->|"HTTP / extension protocols"| runtime - source["Remote source and untrusted content"] -->|"collection adapters"| runtime - runtime -->|"runtime role"| database["PostgreSQL / info-base"] - runtime -->|"configured requests and selected data"| provider["External providers"] - artifact["Reviewed built-in extension code"] -->|"runs in-process"| runtime -``` - -The arrows describe boundaries, not a promise that every deployment exposes every path. -Transport termination, host isolation, backups, and provider access are supplied by the -selected deployment environment and must be assessed with its runtime documentation. - -## Actors And Authority - -| Actor | Security posture | -| --- | --- | -| Deployment owner | Trusted administrator of one single-user deployment. Can configure the runtime, inspect its database and backups, and replace the artifact. | -| Admitted peer client | Inside the deployment trust domain after satisfying the executable peer contract. Current core surfaces do not provide per-user or per-tenant isolation between admitted peers. | -| Untrusted network caller | Has no core authority until admitted by the relevant protocol. Public health/probe routes grant only their documented observations. | -| Extension protocol client | Untrusted until the extension's own admission mechanism succeeds. Its authority is limited by that protocol's intended surface, not by core peer identity. | -| Remote source and collected content | Untrusted data. A configured source may supply malformed, adversarial, stale, or misleading content. Collection does not make content executable or trustworthy. | -| Built-in extension code | Trusted artifact code reviewed and shipped with core. It runs in-process and is not a sandbox or a tenant boundary. Adding third-party extension code is equivalent to adding application code. | -| External provider | Outside the deployment boundary. It receives only requests and data deliberately sent by configured code, subject to the provider's own policy and credentials. | - -## Protected Assets - -- confidentiality and integrity of info-base blocks, relations, raw attachments, and their - derived resolver output; -- credentials and signing material used to admit peers, extension clients, database roles, - sources, and external providers; -- the deployment owner's control over collection, organization, retrieval, configuration, - and deletion; -- artifact, migration, and dependency integrity; -- availability where an untrusted actor can cause meaningful denial, resource exhaustion, - or external cost without already holding equivalent deployment authority. - -## Security Boundaries And Invariants - -### Admission - -Core API and PostgREST admission are one peer trust boundary. Their exact JWT claims, -database roles, and denial behavior are owned by the [Executable Database -Contract](../40-deployment/database-contract.md) and executable tests. - -An extension may expose public, peer-authenticated, or self-authenticated routes. Public -routes must reveal only facts intentionally public for that protocol. Self-authenticated -routes own their credential and authority semantics; successful extension authentication -does not silently grant unrelated core authority. - -CORS, obscurity, route naming, and possession of a client identifier are not authorization -boundaries. +# Core Runtime Security Boundaries + +## Purpose And Authority + +The shared [Security Boundary Model](../_shared/20-product-tdd/security-boundary-model.md) +owns InKCre-wide actors，assets，trust boundaries，security classification and proportionality +method。This document records only how `core-py` realizes those boundaries。 + +External vulnerability reporting is owned by the root [Security Policy](../../SECURITY.md)。 +Executable authentication，database and runtime behavior remains owned by code，tests，CI and +the linked deployment contracts。 + +## Runtime Scope + +This local projection covers the FastAPI runtime，the executable PostgreSQL contract，built-in +Extension loading，Source collection，Resolver/Storage access，background Jobs and the artifacts +and deployment surfaces delivered by this repository。 + +Browser rendering，native-client storage and other Peer-local mechanics belong to their owning +repositories。Concrete Extension protocol credentials and admission belong to the Extension's +local durable contract。 + +## Local Boundary Realization + +### Core And Database Peer Admission + +Core API and PostgREST realize one admitted Peer trust boundary。Their exact JWT claims，database +roles，grants and denial behavior are owned by the [Executable Database +Contract](../40-deployment/database-contract.md) and its executable checks。 + +Public health and probe routes grant only their documented observations。CORS，route naming and +client identifiers do not add authority。 + +### Extension Protocols + +An Extension may expose public，Peer-authenticated or Extension-authenticated routes as defined by +the shared [Unit Topology](../_shared/20-product-tdd/unit-topology.md)。Successful Extension +authentication does not grant unrelated core authority。 + +Built-in Extensions run as reviewed in-process application code。The registry organizes runtime +capabilities；it does not isolate an Extension from the process or database authority intentionally +available to application code。Concrete protocol mechanics remain with the owning Extension design。 ### Persistence And Credentials -PostgreSQL is inside the deployment trust boundary when accessed by the runtime and -admitted peers. Persisting a credential in an access-controlled configuration row is not, -by itself, a boundary violation. The relevant requirements are that it is not exposed to -unauthorized callers, logs, public artifacts, or unrelated protocols, and that its lifetime -and replacement behavior match the product need. - -Encryption at rest, an external secret manager, or non-persistence may be valuable -hardening when the deployment adds an untrusted database operator, independently exposed -backups, multiple users, regulatory duties, or another concrete boundary. Those controls -are not automatic requirements in the current single-owner model. - -### Data And Code - -Collected text, metadata, media, filenames, provider responses, resolver input, and LLM -input are data controlled partly or wholly by external parties. They must not become code, -filesystem paths, SQL, templates, privileged commands, or authorization decisions without -an explicit validating boundary. - -Storing or resolving adversarial content is not itself a vulnerability. Executing it, -letting it escape its intended data context, or allowing it to drive privileged behavior -may be one. Downstream clients remain responsible for safe rendering and interaction in -their own repositories. - -### Extensions And Supply Chain - -Built-in extensions share the runtime's process and database authority. The extension -registry is an organization mechanism, not a security sandbox. Runtime installation of -unreviewed code is outside the current product contract; reviewed artifact construction, -locked dependencies, migration integrity, and CI checks are the relevant supply-chain -boundaries. - -### Runtime And Operations - -The deployment owner, host administrator, migration owner, and anyone able to replace the -running artifact are already inside the highest local authority boundary. Protecting a -deployment from its own fully privileged operator is not a current goal. - -Public health surfaces must not disclose credentials, provider exceptions, or database -URLs. Runtime ownership, readiness, reset guards, credential locations, and cleanup are -owned by the [Deployment documentation](../40-deployment/README.md). - -## What Usually Constitutes A Vulnerability - -Examples include a plausible path for an actor to: - -- read, create, change, or delete protected data without the authority intended by the - relevant protocol; -- forge or bypass admission and gain materially greater authority; -- cause attacker-controlled data to execute code or privileged commands; -- expose credentials or private content across an intended boundary through responses, - logs, artifacts, caches, or providers; -- compromise artifact, migration, or dependency integrity in a way that reaches users; -- cause material denial of service or external cost from an otherwise untrusted position. - -A report needs both security harm and an attack path. A surprising behavior, best-practice -deviation, missing defense-in-depth layer, or hypothetical consequence without a boundary -crossing is not enough on its own. - -## Non-Boundaries And Common False Positives - -The following are not vulnerabilities under the current model unless additional evidence -introduces a different actor or boundary: - -- the deployment owner reading or changing its own database, configuration, backups, or - process memory; -- one admitted peer exercising capability intentionally shared with admitted peers; -- trusted built-in extension code reaching runtime resources available to application - code; -- a credential being persisted inside the access-controlled deployment boundary; -- lack of encryption at rest or an extra authentication layer without a demonstrated - unauthorized reader or caller; -- malformed or hostile collected content being stored as inert data; -- an architectural hardening opportunity described without an exploit path or user harm; -- behavior that requires prior host-administrator, migration-owner, or artifact-replacement - authority. - -These observations can still justify maintainability, privacy, reliability, or -defense-in-depth work. Classifying them accurately prevents that work from borrowing false -urgency from the word "vulnerability." - -## Proportionality Method - -Before requiring a security control or classifying a report, write down: - -1. **Actor and capability**: who acts, and what authority do they already possess? -2. **Asset and harm**: what protected interest changes, leaks, executes, or becomes - unavailable? -3. **Boundary**: what intended separation is crossed? -4. **Attack path**: what reproducible or technically credible steps connect actor to harm? -5. **Existing controls**: which code, tests, deployment controls, or operational assumptions - already reduce the risk? -6. **Control cost**: what complexity, failure mode, user friction, or operational burden - would the proposed control introduce? -7. **Classification**: vulnerability, ordinary bug, hardening, operational risk, or accepted - risk? - -Prefer the least complex control that materially changes the identified risk. Re-evaluate -the classification when deployment assumptions change; do not preserve an old answer by -turning it into a timeless slogan. - -## Worked Boundary Check: Extension PAT Persistence - -The Memos PAT admits a protocol client to a deployment-scoped extension. The current -deployment is single-owner, extension configuration is already persisted in PostgreSQL, -and database/runtime operators are trusted administrators. The intended boundary is -between an unauthenticated protocol caller and the Memos backend, not between the owner and -its own database. - -Therefore, storing the PAT in validated extension configuration is acceptable in this -model. Required controls concern request-time comparison, replacement/revocation, -authorization of config access, and avoiding public/log/artifact disclosure. Forcing the -PAT into a separate non-persistent channel would add configuration and lifecycle complexity -without protecting it from a different current actor. - -That conclusion must change if the product introduces untrusted database readers, -separately exposed backups, multi-user isolation, delegated extension administration, or a -compliance requirement. The method is stable; the result is conditional on the model. - -## Review And Ownership - -- Security reporting and disclosure: [Security Policy](../../SECURITY.md) -- Internal graph/source/resolver authority: [Business Pipeline And - Authority](business-pipeline-and-authority.md) -- Database roles, JWT, and protocol admission: [Executable Database - Contract](../40-deployment/database-contract.md) -- Runtime, health, and operational ownership: [Deployment - documentation](../40-deployment/README.md) -- Enforced dependency admission: [repository CI](../../.github/workflows/ci.yml) - -Update this model when an actor, asset, deployment assumption, or trust boundary changes. -Do not duplicate implementation details here merely because they are security-relevant. +PostgreSQL is inside the current deployment trust boundary when accessed by the runtime and +admitted Peers。Credentials may be ordinary access-controlled configuration when that matches the +owning protocol。Exact config authorization，logging and replacement behavior belongs to the +implementing Unit；the shared model determines whether another deployment topology requires a +stronger boundary。 + +### External Data And Providers + +Collected text，metadata，media，filenames，Resolver input and provider responses remain untrusted +data。Collection and resolution do not make them executable or authoritative。Adapters，Resolvers， +Storages and presentation Peers each own validation where data crosses into a more privileged +interpretation。 + +Configured external providers receive only requests and data selected by the calling capability。 +Provider credentials and response handling remain owned by that capability and its runtime config。 + +### Runtime And Delivery + +The deployment owner，host administrator，migration authority and artifact publisher already hold +their documented operational authority。Runtime ownership，readiness，database lifecycle，credential +locations and live delivery are owned by the [Deployment documentation](../40-deployment/README.md)。 + +Public observations must not expose credentials，database URLs or unrelated provider failures。 +Artifact，migration and dependency integrity is enforced by repository code and CI rather than +restated as prose here。 + +## Local Review Routing + +Use the shared security model to classify an observation，then inspect the executable owner： + +- database roles，JWT and Peer protocol admission：[Executable Database + Contract](../40-deployment/database-contract.md)； +- graph，Source，Resolver and Storage authority：[Business Pipeline And + Authority](business-pipeline-and-authority.md)； +- one Extension's protocol or credential：that Extension's local Unit design； +- runtime，health and delivery：[Deployment documentation](../40-deployment/README.md)； +- external reporting and disclosure：[Security Policy](../../SECURITY.md)。 + +Update this note only when core-py's realization of a shared boundary changes。Update the Hub model +first when the actor，asset，boundary or classification method changes across InKCre。 diff --git a/docs/_shared b/docs/_shared index 3296867..ecfe286 160000 --- a/docs/_shared +++ b/docs/_shared @@ -1 +1 @@ -Subproject commit 3296867c3d47f285686703a919c3adef0b3b3d43 +Subproject commit ecfe286a650f712c92600e977b5532642129d796 diff --git a/docs/index.md b/docs/index.md index 98885df..9739c37 100644 --- a/docs/index.md +++ b/docs/index.md @@ -2,7 +2,7 @@ - Shared product truth: [`_shared/10-prd/`](_shared/10-prd/) - Shared cross-unit contracts: [`_shared/20-product-tdd/`](_shared/20-product-tdd/) -- Local unit design and security model: [`30-unit-tdd/README.md`](30-unit-tdd/README.md) +- Local unit design and runtime security boundaries: [`30-unit-tdd/README.md`](30-unit-tdd/README.md) - Deployment and runtime truth: [`40-deployment/`](40-deployment/) - Vulnerability reporting policy: [`../SECURITY.md`](../SECURITY.md) - Active agent-owned work: [`../tasks/`](../tasks/)