Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
50 changes: 50 additions & 0 deletions .github/CODEOWNERS
Original file line number Diff line number Diff line change
@@ -0,0 +1,50 @@
# Ownership here means protected review, not notification: a change to a
# surface below cannot merge without an owner's approval once the branch
# ruleset in docs/GOVERNANCE.md is applied. The policy — what each surface is
# and why it needs an owner — lives in docs/GOVERNANCE.md, which this file
# must stay consistent with.
#
# Accountable owner per OpenCoven/psyche#14: @BunsDev. Team-scoped entries may
# refine this file; until teams exist, ownership is the named maintainers.

# Default: everything requires maintainer review.
* @BunsDev @CompleteDotTech

# Core contracts: canonical records, digests, IDs, the closed v1 registry, and
# the error vocabulary every other crate and consumer inherits.
/crates/psyche-core/ @BunsDev @CompleteDotTech

# Store: durable records, append-only transitions, quarantine, retention, and
# the forward-only migrations that decide what older binaries can still open.
/crates/psyche-store/ @BunsDev @CompleteDotTech
/crates/psyche-store/migrations/ @BunsDev @CompleteDotTech

# Coven boundary: the typed port contracts downstream repositories bind to.
/crates/psyche-coven/ @BunsDev @CompleteDotTech

# Surfaces: bounded adapter ports; the wall against payload widening.
/crates/psyche-surfaces/ @BunsDev @CompleteDotTech

# Conformance: the reusable C-S suites, fakes, and state-machine evidence.
/crates/psyche-test-support/ @BunsDev @CompleteDotTech

# Evidence: the attestations and the checkers that verify they stay true.
/docs/G2-EVIDENCE.md @BunsDev @CompleteDotTech
/scripts/ @BunsDev @CompleteDotTech

# Runtime, configuration, and CLI: startup, shutdown, and operator surface.
/crates/psyche-runtime/ @BunsDev @CompleteDotTech
/crates/psyche-config/ @BunsDev @CompleteDotTech
/crates/psyche-cli/ @BunsDev @CompleteDotTech

# CI: the checks every other surface is gated by. Changes here can weaken
# every guarantee at once and are reviewed like contract changes.
/.github/ @BunsDev @CompleteDotTech

# Release: what actually ships, and the manifests that make it verifiable.
/packages/ @BunsDev @CompleteDotTech
/docs/RELEASE.md @BunsDev @CompleteDotTech

# Docs: what consumers and operators rely on being true.
/docs/ @BunsDev @CompleteDotTech
/*.md @BunsDev @CompleteDotTech
8 changes: 8 additions & 0 deletions .github/ISSUE_TEMPLATE/config.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,8 @@
blank_issues_enabled: false
contact_links:
- name: Security vulnerability
url: https://github.com/OpenCoven/psyche/security/advisories/new
about: Private disclosure route. Never a public issue — see SECURITY.md.
- name: Support and reporting guide
url: https://github.com/OpenCoven/psyche/blob/main/SUPPORT.md
about: What to include in a report, and what never to include.
56 changes: 56 additions & 0 deletions .github/ISSUE_TEMPLATE/contract-and-conformance.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,56 @@
name: Contract and conformance
description: Propose a schema/profile change or report a conformance gap against the frozen contracts.
labels: ["contract"]
body:
- type: markdown
attributes:
value: |
This issue is public and permanent. Never include secrets or credential
values, raw prompts or private conversation content, unrestricted
terminal output, private repository data, environment dumps, or full
personal paths.

The v1 registry is closed: an unknown kind, unknown major version, or
unknown enum value is a strict decode failure and quarantines, never
dispatches. A proposal here is a proposal to revise that registry
deliberately, through review — not a bug in the refusal.

- type: dropdown
id: kind
attributes:
label: Kind
options:
- Schema or profile change proposal
- Conformance gap (a suite accepts or rejects wrongly)
- Error vocabulary gap
- Digest or canonicalization concern
validations:
required: true

- type: textarea
id: affected
attributes:
label: Affected schema kinds
description: The exact identifiers, e.g. psyche.delivery.v1, psyche.error.v1. The closed registry is listed in docs/SCHEMAS.md.
validations:
required: true

- type: textarea
id: behavior
attributes:
label: Expected vs actual behavior
description: For a conformance gap, name the suite (C-S1 through C-S12, docs/TESTING.md) and the exact step.
validations:
required: true

- type: textarea
id: evidence
attributes:
label: Evidence links
description: Immutable URLs to source, runs, or fixtures — with the SHA-256 where one exists, as docs/G2-EVIDENCE.md does. Do not paste private repository data; link what is public or describe it abstractly.

- type: textarea
id: compatibility
attributes:
label: Compatibility consequence
description: What a consumer on the current registry would see after this change, and what migration or quarantine behavior follows.
67 changes: 67 additions & 0 deletions .github/ISSUE_TEMPLATE/defect.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,67 @@
name: Defect report
description: Report a defect or regression in Psyche. This form exists to keep protected data out of public issues.
labels: ["defect"]
body:
- type: markdown
attributes:
value: |
This issue is public and permanent. Never include secrets or credential
values, raw prompts or private conversation content, unrestricted
terminal output, private repository data, environment dumps (`env`,
`set`, process listings), or full personal paths. Replace home
directories with `~` (or `%USERPROFILE%`) everywhere, including in JSON.

If you believe you have found a **vulnerability**, do not use this
form: follow the private route in SECURITY.md
(https://github.com/OpenCoven/psyche/security/advisories/new).

- type: textarea
id: observed
attributes:
label: What happened
description: The observed behavior, trimmed to what matters.
validations:
required: true

- type: textarea
id: expected
attributes:
label: What you expected
description: And why that expectation matches the documented behavior — docs/CLI.md, docs/CONFIGURATION.md, docs/SCHEMAS.md, or a conformance suite.

- type: textarea
id: doctor
attributes:
label: Doctor output
description: |
`psyche doctor --json`. Safe to paste by design: it never reads a
credential and never contacts the network. Still redact personal paths.
render: json

- type: textarea
id: terminal
attributes:
label: Failing command and output
description: The one command that failed and its error output only — not a transcript of the session.

- type: input
id: version
attributes:
label: Version or commit
description: The commit if built from source, or the package version once packages exist.
validations:
required: true

- type: input
id: platform
attributes:
label: Platform
description: OS and architecture, e.g. linux-x64, darwin-arm64, win32-x64.
validations:
required: true

- type: input
id: schema-version
attributes:
label: Configured schema_version
description: The declared value, e.g. psyche.config.v1. Do not paste the configuration file itself.
51 changes: 51 additions & 0 deletions .github/PULL_REQUEST_TEMPLATE.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,51 @@
<!--
Every section is required. A section that does not apply says "None" and says
why in one sentence — a template that lets "None" stand silently is a template
that gets skipped. Sections align with docs/GOVERNANCE.md and the branch
ruleset policy; reviewers for the paths in .github/CODEOWNERS are required
reviewers once that policy is applied.
-->

## Summary

<!-- What changes and why, in a few sentences. What is true after this PR that was not true before. -->

## Scope

<!-- Surfaces touched: core contracts / store / coven boundary / surfaces / test-support / runtime / cli / npm wrapper / CI / docs. One line each, or "docs only". -->

## Risk

<!-- What breaks if this change is wrong, and what contains the blast radius. For contract changes: which invariants hold this together. -->

## Contract impact

<!-- Changes to psyche.* schema kinds, major versions, the closed v1 registry, error codes, digest computation, or record identity. "None" must mean none of those bytes changed. -->

## Migration

<!-- Store migrations added or changed? A schema version bump? Forward-only? What happens to a store written by the previous build. "None" means the store schema is untouched. -->

## Rollback

<!-- How to revert this safely after it lands, including what happens to data the change has already written. "Revert the commit" is an answer only when it is the whole answer. -->

## Generated artifacts

<!-- Fixtures, canonical JSON, digests, manifests, SBOMs, packed tarballs regenerated by this change — and the command that regenerates them. "None" means nothing generated changed. -->

## Tests

<!-- Checked = ran locally. Unchecked = deferred to CI; say which. Targeted tests for the touched surfaces belong here. -->

- [ ] `cargo fmt --all -- --check`
- [ ] `cargo clippy --workspace --all-targets -- -D warnings`
- [ ] `cargo test --workspace --locked`

## Affected consumers

<!-- Who consumes what this changes: coven, downstream adapters, npm users, operators, docs readers. "None" is only available to docs-only changes that change no contract, no schema, and no command behavior. -->

## Issue

Refs OpenCoven/psyche#
97 changes: 97 additions & 0 deletions SECURITY.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,97 @@
# Security policy

This file states what security support exists today, where to report a
vulnerability privately, what happens after a report, and where ordinary
support ends. It describes the repository as it is; a release that cannot keep
these promises cannot claim them.

## Supported versions and surfaces

Psyche has no released versions. The npm packages are not published
(publication is gated at G12), the Rust workspace version is `0.0.0`, and no
tag exists. The only supported version is the `main` branch:

| Surface | Status | Security fixes |
|---|---|---|
| `psyche` / `psyched` built from `main` | development build | fixed on `main` |
| SQLite store under the configured `data_dir` | development build | fixed on `main` |
| Coven socket boundary (typed port contracts) | development build | fixed on `main` |
| `@opencoven/psyche` npm wrapper | **not published** | none until first publish |
| Tagged or packaged releases | none exist | not applicable |

Until the first tagged release there is nothing to backport to: a security fix
is a commit on `main`. The backport and support-window policy in
[docs/RELEASE.md](docs/RELEASE.md) begins operating with the first stable
release, not before.

## The surfaces, concretely

A security report should name one of these. Claims here are enforced by code
and pinned by tests; where this build does not yet enforce something, the
enforcement gap is stated in the same breath.

- **Configuration.** The root config declares `psyche.config.v1` exactly;
unknown fields and unknown versions are errors. Secrets are named by
reference (`op://VAULT/ITEM/token`), never as literals — the `SecretRef` type
rejects a literal at parse time. In this release no field is typed as
`SecretRef` yet, so that rejection has nothing to act on; the gap is
recorded in [docs/CONFIGURATION.md](docs/CONFIGURATION.md) rather than
hidden here.
- **Data directory.** The store refuses to run with unsafe filesystem
permissions and fails closed rather than auto-relaxing them;
`psyche doctor` reports the same conditions without auto-fixing them.
- **Coven socket.** The daemon binds the socket configured at `coven.socket`.
The typed port contracts in `psyche-coven` and `psyche-surfaces` bound what
crosses it; adapters cannot widen payloads or add fields.
- **Logs and documents.** Logs are JSON on stderr, `--json` documents on
stdout. Extension-table values are never printed, and a `Config` is never
rendered with `{:?}` — both pinned by tests — because a future extension may
carry a credential.
- **npm wrapper.** The wrapper verifies the platform binary's SHA-256 against
a recorded manifest before exec and fails closed: the shipped digests are
placeholders that match no artifact, so the wrapper is inert until a release
replaces them. Its limits are stated in the package README — it is a
time-of-check/time-of-use check that authenticates the manifest's claim, not
the publisher.

## Reporting a vulnerability

Report privately through GitHub's private vulnerability reporting:
**https://github.com/OpenCoven/psyche/security/advisories/new**

Never report a security problem in a public issue, a pull request, or any
other channel — a public report discloses the vulnerability before a fix can
exist.

A report is usable with: the commit or package version, the surface above,
a minimal reproduction, and the impact you observed. A report must not
contain secrets or credential values, raw prompts or private conversation
content, unrestricted terminal output, private repository data, environment
dumps, or full personal paths — redact home directories to `~` (or
`%USERPROFILE%`). [SUPPORT.md](SUPPORT.md) explains how to trim a
report without trimming what matters.

## What happens after a report

| Step | Target |
|---|---|
| Acknowledgement | within 5 business days |
| Status update | every 14 days until resolution |
| Fix | on `main` (backports begin with the first stable release) |
| Coordinated disclosure | with the fix release, or within 90 days of confirmation, whichever comes first |

The advisory is published when affected users can act on it, not before.
Credit is given at the reporter's discretion. No bounty program exists.

## What is not security support

Security reporting is not a support channel. Installation help, configuration
questions, and defect reports belong in the ordinary support routes in
[SUPPORT.md](SUPPORT.md). Out of scope for the security process:

- a compromised operator account or host (fix the host; the daemon cannot
defend an attacker who can edit its configuration file and data directory),
- defects in the Coven daemon on the other end of the socket, or in any
messaging surface behind it — report those to their own projects,
- anything that requires a listening network service beyond the configured
Coven socket or a global guarantee the wrapper's README does not make.
Loading