docs: module dossier + install/quickstart sync for truthful cutover sprints
- API_CLI_REFERENCE.md, INSTALL_GUIDE.md, quickstart.md, architecture/integrations.md, dev/DEV_ENVIRONMENT_SETUP.md, integrations/LOCAL_SERVICES.md: reflect real-service wiring. - docs/modules/**: module dossier updates across the modules touched by SPRINT_20260415_001..007 + SPRINT_20260416_003..017 + SPRINT_20260417_018..024 + SPRINT_20260418_025 + SPRINT_20260419_026. - docs/features/checked/web/**: update feature notes where UI changed. - docs/qa/feature-checks/runs/web/evidence-presentation-ux/: QA evidence artifacts. - docs/setup/**, docs/technical/**: align with setup wizard contracts. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
master
@@ -120,20 +120,27 @@ Database: `attestor`
|
||||
|
||||
```sql
|
||||
CREATE TABLE attestor.entries (
|
||||
id UUID PRIMARY KEY, -- rekor-uuid
|
||||
rekor_uuid TEXT PRIMARY KEY,
|
||||
bundle_sha256 TEXT NOT NULL UNIQUE,
|
||||
artifact_sha256 TEXT NOT NULL,
|
||||
artifact_kind TEXT NOT NULL, -- sbom|report|vex-export
|
||||
artifact_kind TEXT NOT NULL, -- sbom|report|vex-export|policy-eval
|
||||
artifact_image_digest TEXT,
|
||||
artifact_subject_uri TEXT,
|
||||
bundle_sha256 TEXT NOT NULL, -- canonicalized DSSE
|
||||
log_index INTEGER, -- log index/sequence if provided by backend
|
||||
proof_checkpoint JSONB, -- { origin, size, rootHash, timestamp }
|
||||
proof_inclusion JSONB, -- { leafHash, path[] } Merkle path (tiles)
|
||||
log_url TEXT,
|
||||
log_index BIGINT,
|
||||
log_backend TEXT NOT NULL,
|
||||
log_url TEXT NOT NULL,
|
||||
log_id TEXT,
|
||||
log_integrated_time BIGINT,
|
||||
created_at TIMESTAMPTZ DEFAULT NOW(),
|
||||
updated_at TIMESTAMPTZ DEFAULT NOW(),
|
||||
status TEXT NOT NULL, -- included|pending|failed
|
||||
signer_identity JSONB -- { mode, issuer, san?, kid? }
|
||||
signer_mode TEXT NOT NULL,
|
||||
signer_issuer TEXT,
|
||||
signer_subject_alternative_name TEXT,
|
||||
signer_key_id TEXT,
|
||||
proof JSONB, -- canonical Rekor checkpoint + inclusion proof
|
||||
witness JSONB,
|
||||
mirror JSONB
|
||||
);
|
||||
```
|
||||
|
||||
@@ -148,27 +155,27 @@ Database: `attestor`
|
||||
);
|
||||
```
|
||||
|
||||
* `audit` table
|
||||
* `audit log` table
|
||||
|
||||
```sql
|
||||
CREATE TABLE attestor.audit (
|
||||
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
|
||||
ts TIMESTAMPTZ DEFAULT NOW(),
|
||||
caller_cn TEXT,
|
||||
caller_mtls_thumbprint TEXT,
|
||||
caller_sub TEXT,
|
||||
caller_aud TEXT,
|
||||
action TEXT NOT NULL, -- submit|verify|fetch
|
||||
artifact_sha256 TEXT,
|
||||
bundle_sha256 TEXT,
|
||||
rekor_uuid UUID,
|
||||
log_index INTEGER,
|
||||
result TEXT NOT NULL,
|
||||
latency_ms INTEGER,
|
||||
backend TEXT
|
||||
CREATE TABLE proofchain.audit_log (
|
||||
log_id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
|
||||
operation TEXT NOT NULL,
|
||||
entity_type TEXT NOT NULL,
|
||||
entity_id TEXT NOT NULL,
|
||||
actor TEXT,
|
||||
details JSONB,
|
||||
created_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
|
||||
);
|
||||
```
|
||||
|
||||
* `watchlist` tables
|
||||
|
||||
```sql
|
||||
CREATE TABLE attestor.identity_watchlist (...);
|
||||
CREATE TABLE attestor.identity_alert_dedup (...);
|
||||
```
|
||||
|
||||
Indexes:
|
||||
|
||||
* `entries`: indexes on `artifact_sha256`, `bundle_sha256`, `created_at`, and composite `(status, created_at DESC)`.
|
||||
@@ -506,9 +513,13 @@ The exception signing service provides endpoints for signing, verifying, and ren
|
||||
|
||||
### 4.5 Bulk verification
|
||||
|
||||
`POST /api/v1/rekor/verify:bulk` enqueues a verification job containing up to `quotas.bulk.maxItemsPerJob` items. Each item mirrors the single verification payload (uuid | artifactSha256 | subject+envelopeId, optional policyVersion/refreshProof). The handler persists a PostgreSQL job record (`bulk_jobs` table) and returns `202 Accepted` with a job descriptor and polling URL.
|
||||
Note (2026-04-16): non-testing runtime now returns truthful `501 Not Implemented` for the bulk verification endpoints until a durable bulk job store plus worker path exists. The previous in-memory queue behavior is test-only.
|
||||
|
||||
`GET /api/v1/rekor/verify:bulk/{jobId}` returns progress and per-item results (subject/uuid, status, issues, cached verification report if available). Jobs are tenant- and subject-scoped; only the initiating principal can read their progress.
|
||||
Historical design note below is retained for the future durable implementation. It is not the current live host behavior.
|
||||
|
||||
When the durable worker ships, `POST /api/v1/rekor/verify:bulk` should enqueue a verification job containing up to `quotas.bulk.maxItemsPerJob` items and return `202 Accepted` with a job descriptor plus polling URL.
|
||||
|
||||
When the durable worker ships, `GET /api/v1/rekor/verify:bulk/{jobId}` should return progress and per-item results (subject/uuid, status, issues, cached verification report if available). Jobs remain tenant- and subject-scoped; only the initiating principal can read their progress.
|
||||
|
||||
**Worker path:** `BulkVerificationWorker` claims queued jobs (`status=queued → running`), executes items sequentially through the cached verification service, updates progress counters, and records metrics:
|
||||
|
||||
@@ -935,6 +946,8 @@ The Attestor provides proactive monitoring for signing identities appearing in t
|
||||
|
||||
Authorization for the live watchlist surface follows the canonical trust scope family (`trust:read`, `trust:write`, `trust:admin`). The service still accepts legacy `watchlist:*` aliases for backward compatibility, but new clients and UI sessions should rely on the trust scopes.
|
||||
|
||||
Non-testing runtime persists watchlist state in PostgreSQL (`attestor.identity_watchlist`, `attestor.identity_alert_dedup`) and reserves in-memory watchlist storage for test harnesses only.
|
||||
|
||||
### Event Flow
|
||||
|
||||
```
|
||||
@@ -2695,17 +2708,17 @@ Source consolidation places all trust-domain code under a single directory for o
|
||||
| Attestation evidence (proofchain, inclusion proofs, Rekor entries) | Attestor | `attestor` PostgreSQL schema | High -- tamper-evident, integrity-critical |
|
||||
| Provenance evidence (SLSA predicates, build attestations, Merkle trees) | Provenance (library) | Consumed by Attestor/EvidenceLocker | High -- deterministic, reproducible |
|
||||
| Signer metadata (audit events, signing ceremony state, rate limits) | Signer | `signer` PostgreSQL schema | High -- operational security |
|
||||
| Signer key material (KMS/HSM refs, Fulcio certs, trust anchors, rotation state) | Signer (KeyManagement) | `key_management` PostgreSQL schema | Critical -- cryptographic trust root |
|
||||
| Signer key material (KMS/HSM refs, Fulcio certs, trust anchors, rotation state) | Signer (KeyManagement) | `signer` PostgreSQL schema | Critical -- cryptographic trust root |
|
||||
|
||||
### PostgreSQL Schema Ownership
|
||||
|
||||
Each trust-domain service retains its own DbContext and dedicated PostgreSQL schema:
|
||||
|
||||
- **`attestor` schema** -- Owned by the Attestor service. Contains `entries`, `dedupe`, `audit` tables for transparency log state.
|
||||
- **`signer` schema** -- Owned by the Signer service. Contains signing ceremony audit, rate limit state, and operational metadata.
|
||||
- **`key_management` schema** -- Owned by the Signer KeyManagement library. Contains key rotation records, trust anchor configurations, and HSM/KMS binding metadata.
|
||||
- **`signer` schema** -- Owned by the Signer trust-domain runtime. Contains ceremony state/audit plus key-management tables (`trust_anchors`, `key_history`, `key_audit_log`) that the live Signer host auto-migrates on startup.
|
||||
- **KeyManagement library boundary** -- Key rotation, trust anchor management, and HSM/KMS binding logic remain isolated in the `StellaOps.Signer.KeyManagement` library, but the canonical runtime tables now live inside the `signer` schema rather than a separate `key_management` schema.
|
||||
|
||||
There is **no cross-schema merge**. Each service connects with its own connection string scoped to its own schema.
|
||||
There is **no cross-service schema merge**. Attestor evidence state remains isolated from Signer runtime state, and the Signer host now requires a real KeyManagement connection string outside `Testing`. The stub bearer path is test-only and is not part of the live composition root.
|
||||
|
||||
### Security Boundary: No-Merge Decision (ADR)
|
||||
|
||||
|
||||
Reference in New Issue
Block a user