# component_architecture_signer.md — **Stella Ops Signer** (2025Q4)

> Supports deliverables from Epic 10 – Export Center and Epic 19 – Attestor Console.

> **Scope.** Implementation‑ready architecture for the **Signer**: the *only* service allowed to produce **Stella Ops‑verified** signatures over SBOMs and reports. It enforces **entitlement** (PoE), **release integrity** (scanner provenance), **sender‑constrained auth** (DPoP/mTLS), and emits **in‑toto/DSSE** bundles suitable for **Rekor v2** logging by the Attestor. Includes APIs, data flow, storage, quotas, security, and test matrices.

---

## 0) Mission & boundaries

**Mission.** Convert authenticated signing requests from trusted Stella Ops services into **verifiable** DSSE bundles while enforcing **license policy** and **supply‑chain integrity**.

**Boundaries.**

* **Signer does not push to Rekor** — it returns DSSE to the caller; **Attestor** logs to **Rekor v2**.
* **Signer does not compute PASS/FAIL** — it signs SBOMs/reports produced by Scanner/WebService after backend evaluation.
* **Signer is stateless for hot path** — long‑term storage is limited to audit events; all secrets/keys live in KMS/HSM or are ephemeral (keyless).

---

## 1) Responsibilities (contract)

1. **Authenticate** caller with **OpTok** (Authority OIDC, DPoP or mTLS‑bound).
2. **Authorize** scopes (`signer.sign`) + audience (`aud=signer`) + tenant/installation.
3. **Validate entitlement** via **PoE** (Proof‑of‑Entitlement) against Cloud Licensing `/license/introspect`.
4. **Verify release integrity** of the **scanner** image digest presented in the request: must be **cosign‑signed** by Stella Ops release key, discoverable via **OCI Referrers API**.
5. **Enforce plan & quotas** (concurrency/QPS/artifact size/rate caps).
6. **Mint signing identity**:

   * **Keyless** (default): get a short‑lived X.509 cert from **Fulcio** using the Signer’s OIDC identity and sign the DSSE.
   * **Keyful** (optional): sign with an HSM/KMS key.
7. **Return DSSE bundle** (subject digests + predicate + cert chain or KMS key id).
8. **Audit** every decision; expose metrics.

---

## 2) External dependencies

* **Authority** (on‑prem OIDC): validates OpToks (JWKS/introspection) and DPoP/mTLS.
* **Licensing Service (cloud)**: `/license/introspect` to verify PoE (active, claims, expiry, revocation).
* **Fulcio** (Sigstore) *or* **KMS/HSM**: to obtain certs or perform signatures.
* **OCI Registry (Referrers API)**: to verify **scanner** image release signature.
* **Attestor**: downstream service that writes DSSE bundles to **Rekor v2**.
* **Config/state stores**: Redis (caches, rate buckets), Mongo/Postgres (audit log).

---

## 3) API surface (mTLS; DPoP supported)

Base path: `/api/v1/signer`. **All endpoints require**:

* Access token (JWT) from **Authority** with `aud=signer`, `scope=signer.sign`.
* **Sender constraint**: DPoP proof per request or mTLS client cert.
* **PoE** presented as either:

  * **Client TLS cert** (if PoE is mTLS‑style) chained to Licensing CA, *or*
  * **PoE JWT** (DPoP/mTLS‑bound) in `X-PoE` header or request body.

### 3.1 `POST /sign/dsse`

Request (JSON):

```json
{
  "subject": [
    { "name": "s3://stellaops/images/sha256:.../inventory.cdx.pb",
      "digest": { "sha256": "..." } }
  ],
  "predicateType": "https://stella-ops.org/attestations/sbom/1",
  "predicate": {
    "image_digest": "sha256:...",
    "stellaops_version": "2.3.1 (2027.04)",
    "license_id": "LIC-9F2A...",
    "customer_id": "CUST-ACME",
    "plan": "pro",
    "policy_digest": "sha256:...",        // optional for final reports
    "views": ["inventory", "usage"],
    "created": "2025-10-17T12:34:56Z"
  },
  "scannerImageDigest": "sha256:sc-web-or-worker-digest",
  "poe": {
    "format": "jwt",                      // or "mtls"
    "value": "eyJhbGciOi..."              // PoE JWT when not using mTLS PoE
  },
  "options": {
    "signingMode": "keyless",             // "keyless" | "kms"
    "expirySeconds": 600,                 // cert lifetime hint (keyless)
    "returnBundle": "dsse+cert"           // dsse (default) | dsse+cert
  }
}
```

Response 200:

```json
{
  "bundle": {
    "dsse": { "payloadType": "application/vnd.in-toto+json", "payload": "<base64>", "signatures": [ ... ] },
    "certificateChain": [ "-----BEGIN CERTIFICATE-----...", "... root ..." ],
    "mode": "keyless",
    "signingIdentity": { "issuer": "https://fulcio.internal", "san": "urn:stellaops:signer", "certExpiry": "2025-10-17T12:44:56Z" }
  },
  "policy": { "plan": "pro", "maxArtifactBytes": 104857600, "qpsRemaining": 97 },
  "auditId": "a7c9e3f2-1b7a-4e87-8c3a-90d7d2c3ad12"
}
```

Errors (RFC 7807):

* `401 invalid_token` (JWT/DPoP/mTLS failure)
* `403 entitlement_denied` (PoE invalid/revoked/expired; release year mismatch)
* `403 release_untrusted` (scanner image not Stella‑signed)
* `429 plan_throttled` (license plan caps)
* `413 artifact_too_large` (size cap)
* `400 invalid_request` (schema/predicate/type invalid)
* `500 signing_unavailable` (Fulcio/KMS outage)

### 3.2 `GET /verify/referrers?imageDigest=<sha256>`

Checks whether the **image** at digest is signed by **Stella Ops release key**.

Response:

```json
{ "trusted": true, "signatures": [ { "type": "cosign", "digest": "sha256:...", "signedBy": "StellaOps Release 2027 Q2" } ] }
```

> **Note:** This endpoint is also used internally by Signer before issuing signatures.

---

### KMS drivers (keyful mode)

Signer now ships five deterministic KMS adapters alongside the default keyless flow:

- `services.AddFileKms(...)` – stores encrypted ECDSA material on disk for air-gapped or lab installs.  
- `services.AddAwsKms(options => { options.Region = "us-east-1"; /* optional: options.Endpoint, UseFipsEndpoint */ });` – delegates signing to AWS KMS, caches metadata/public keys offline, and never exports the private scalar. Rotation/revocation still run through AWS tooling (this library intentionally throws for those APIs so we do not paper over operator approvals).
- `services.AddGcpKms(options => { options.Endpoint = "kms.googleapis.com"; });` – integrates with Google Cloud KMS asymmetric keys, auto-resolves the primary key version when callers omit a version, and verifies signatures locally with exported PEM material.
- `services.AddPkcs11Kms(options => { options.LibraryPath = "/opt/hsm/libpkcs11.so"; options.PrivateKeyLabel = "stella-attestor"; });` – loads a PKCS#11 module, opens read-only sessions, signs digests via HSM mechanisms, and never hoists the private scalar into process memory.
- `services.AddFido2Kms(options => { options.CredentialId = "<base64url>"; options.PublicKeyPem = "-----BEGIN PUBLIC KEY-----..."; options.AuthenticatorFactory = sp => new WebAuthnAuthenticator(); });` – routes signing to a WebAuthn/FIDO2 authenticator for dual-control or air-gap scenarios. The authenticator must supply the CTAP/WebAuthn plumbing; the library handles digesting, key material caching, and verification.

Cloud & hardware-backed drivers share a few invariants:

1. Hash payloads server-side (SHA-256) before invoking provider APIs – signatures remain reproducible and digest inputs are observable in structured audit logs.  
2. Cache metadata for the configurable window (default 5 min) and subject-public-key-info blobs for 10 min; tune these per sovereignty policy when running in sealed/offline environments.  
3. Only expose public coordinates (`Qx`, `Qy`) to the host ― `KmsKeyMaterial.D` is blank for non-exportable keys so downstream code cannot accidentally persist secrets.  

> **Security review checkpoint:** rotate/destroy remains an administrative action in the provider. Document those runbooks per tenant, and gate AWS/GCP traffic in sealed-mode via the existing egress allowlist. PKCS#11 loads native code, so keep library paths on the allowlist and validate HSM policies separately. FIDO2 authenticators expect an operator in the loop; plan for session timeouts and explicit audit fields when enabling interactive signing.

## 4) Validation pipeline (hot path)

```mermaid
sequenceDiagram
  autonumber
  participant Client as Scanner.WebService
  participant Auth as Authority (OIDC)
  participant Sign as Signer
  participant Lic as Licensing Service (cloud)
  participant Reg as OCI Registry (Referrers)
  participant Ful as Fulcio/KMS

  Client->>Sign: POST /sign/dsse (OpTok + DPoP/mTLS, PoE, request)
  Note over Sign: 1) Validate OpTok, audience, scope, DPoP/mTLS binding
  Sign->>Lic: /license/introspect(PoE)
  Lic-->>Sign: { active, claims: {license_id, plan, valid_release_year, max_version}, exp }
  Note over Sign: 2) Enforce plan/version window and revocation

  Sign->>Reg: Verify scannerImageDigest signed (Referrers + cosign)
  Reg-->>Sign: OK with signer identity
  Note over Sign: 3) Enforce release integrity

  Note over Sign: 4) Enforce quotas (QPS/concurrency/size)
  Sign->>Ful: Mint cert (keyless) or sign via KMS
  Ful-->>Sign: Cert or signature

  Sign-->>Client: DSSE bundle (+cert chain), policy counters, auditId
```

**DPoP nonce dance (when enabled for high‑value ops):**

* If DPoP proof lacks a valid nonce, Signer replies `401` with `WWW-Authenticate: DPoP error="use_dpop_nonce", dpop_nonce="<nonce>"`.
* Client retries with new proof including the nonce; Signer validates nonce and `jti` uniqueness (Redis TTL cache).

---

## 5) Entitlement enforcement (PoE)

* **Accepted forms**:

  * **mTLS PoE**: client presents a **PoE client cert** at TLS handshake; Signer validates chain to **Licensing CA** (CA bundle configured) and calls `/license/introspect` with cert thumbprint + serial.
  * **JWT PoE**: `X-PoE` bearer token (DPoP/mTLS‑bound) is validated (sig + `cnf`) locally (Licensing JWKS) and then **introspected** for status and claims.

* **Claims required**:

  * `license_id`, `plan` (free|pro|enterprise|gov), `valid_release_year`, `max_version`, `exp`.
  * Optional: `tenant_id`, `customer_id`, `entitlements[]`.

* **Enforcements**:

  * Reject if **revoked**, **expired**, **plan mismatch** or **release outside window** (`stellaops_version` in predicate exceeds `max_version` or release date beyond `valid_release_year`).
  * Apply plan **throttles** (QPS/concurrency/artifact bytes) via token‑bucket in Redis keyed by `license_id`.

---

## 6) Release integrity (scanner provenance)

* **Input**: `scannerImageDigest` representing the actual Scanner component that produced the artifact.

* **Check**:

  1. Use **OCI Referrers API** to enumerate signatures of that digest.
  2. Verify **cosign** signatures against the configured **Stella Ops Release** keyring (keyless Fulcio roots *or* keyful public keys).
  3. Optionally require Rekor inclusion for those signatures.

* **Policy**:

  * If not signed by an authorized **Stella Ops Release** identity → **deny**.
  * If signed but **release year** > PoE `valid_release_year` → **deny**.

* **Cache**: LRU of digest → verification result (TTL 10–30 min) to avoid registry thrash.

---

## 7) Signing modes

### 7.1 Keyless (default; Sigstore Fulcio)

* Signer authenticates to **Fulcio** using its on‑prem OIDC identity (client credentials) and requests a **short‑lived cert** (5–10 min).
* Generates **ephemeral keypair**, gets cert for the public key, signs DSSE with the **private key**.
* DSSE **bundle** includes **certificate chain**; verifiers validate to Fulcio root.

### 7.2 Keyful (optional; KMS/HSM)

* Signer uses a configured **KMS** key (AWS KMS, GCP KMS, Azure Key Vault, Vault Transit, or HSM).
* DSSE bundle includes **key metadata** (kid, cert chain if x509).
* Recommended for FIPS/sovereign environments.

---

## 8) Predicates & schema

Supported **predicate types** (extensible):

* `https://stella-ops.org/attestations/sbom/1` (SBOM emissions)
* `https://stella-ops.org/attestations/report/1` (final PASS/FAIL reports)
* `https://stella-ops.org/attestations/vex-export/1` (Excititor exports; optional)

**Validation**:

* JSON‑Schema per predicate type; **canonical property order**.
* `subject[*].digest` must include `sha256`.
* `predicate.stellaops_version` must parse and match policy windows.

---

## 9) Quotas & throttling

Per `license_id` (from PoE):

* **QPS** (token bucket), **concurrency** (semaphore), **artifact bytes** (sliding window).
* On exceed → `429 plan_throttled` with `Retry-After`.
* Free/community plan may also receive **randomized delay** to disincentivize farmed signing.

---

## 10) Storage & caches

* **Redis**:

  * DPoP nonce & `jti` replay cache (TTL ≤ 10 min).
  * PoE introspection cache (short TTL, e.g., 60–120 s).
  * Release‑verify cache (`scannerImageDigest` → { trusted, ts }).

* **Audit store** (Mongo or Postgres): `signer.audit_events`

```
{ _id, ts, tenantId, installationId, licenseId, customerId,
  plan, actor{sub,cnf}, request{predicateType, subjectSha256[], imageDigest},
  poe{type, thumbprint|jwtKid, exp, introspectSnapshot},
  release{digest, signerId, policy},
  mode: "keyless"|"kms",
  result: "success"|"deny:<reason>"|"error:<reason>",
  bundleSha256? }
```

* **Config**: Stella Ops release signing keyring, Fulcio roots, Licensing CA bundle.

---

## 11) Security & privacy

* **mTLS** on all Signer endpoints.
* **No bearer fallbacks** — DPoP/mTLS enforced for `aud=signer`.
* **PoE** is never persisted beyond audit snapshots (minimized fields).
* **Secrets**: no long‑lived private keys on disk (keyless) or handled via KMS APIs.
* **Input hardening**: schema‑validate predicates; cap payload sizes; zstd/gzip decompression bombs guarded.
* **Logging**: redact PoE JWTs, access tokens, DPoP proofs; log only hashes and identifiers.

---

## 12) Metrics & observability

* `signer.requests_total{result}`
* `signer.latency_seconds{stage=auth|introspect|release_verify|sign}`
* `signer.poe_failures_total{reason}`
* `signer.release_verify_failures_total{reason}`
* `signer.plan_throttle_total{license_id}`
* `signer.bundle_bytes_total`
* `signer.keyless_certs_issued_total` / `signer.kms_sign_total`
* OTEL traces across stages; correlation id (`auditId`) returned to client.

---

## 13) Configuration (YAML)

```yaml
signer:
  listen: "https://0.0.0.0:8443"
  authority:
    issuer: "https://authority.internal"
    jwksUrl: "https://authority.internal/jwks"
    require: "dpop"         # "dpop" | "mtls"
  poe:
    mode: "both"            # "jwt" | "mtls" | "both"
    licensing:
      introspectUrl: "https://www.stella-ops.org/api/v1/license/introspect"
      caBundle: "/etc/ssl/licensing-ca.pem"
      cacheTtlSeconds: 90
  release:
    referrers:
      allowRekorVerified: true
      keyrings:
        - type: "cosign-keyless"
          fulcioRoots: ["/etc/fulcio/root.pem"]
          identities:
            - san: "mailto:release@stella-ops.org"
            - san: "https://sigstore.dev/oidc/stellaops"
  signing:
    mode: "keyless"         # "keyless" | "kms"
    fulcio:
      issuer: "https://fulcio.internal"
      oidcClientId: "signer"
      oidcClientSecretRef: "env:FULCIO_CLIENT_SECRET"
      certTtlSeconds: 600
    kms:
      provider: "aws-kms"
      keyId: "arn:aws:kms:...:key/..."
  quotas:
    default:
      qps: 100
      concurrency: 20
      maxArtifactBytes: 104857600
    free:
      qps: 5
      concurrency: 1
      maxArtifactBytes: 1048576
```

---

## 14) Testing matrix

* **Auth & DPoP**: bad `aud`, wrong `jkt`, replayed `jti`, missing nonce, mTLS mismatch.
* **PoE**: expired, revoked, plan mismatch, release year gate, max_version gate.
* **Release verify**: unsigned digest, wrong signer, Rekor‑absent (when required), referrers unreachable.
* **Signing**: Fulcio outage; KMS timeouts; bundle correctness (verifier harness).
* **Quotas**: burst above QPS, artifact over size, concurrency overflow.
* **Schema**: invalid predicate types/required fields.
* **Determinism**: same request → identical DSSE (aside from cert validity period).
* **Perf**: P95 end‑to‑end under 120 ms with caches warm (excluding network to Fulcio).

---

## 15) Failure modes & responses

| Failure                 | HTTP | Problem type          | Notes                                        |
| ----------------------- | ---- | --------------------- | -------------------------------------------- |
| Invalid OpTok / DPoP    | 401  | `invalid_token`       | `WWW-Authenticate` with DPoP nonce if needed |
| PoE invalid/revoked     | 403  | `entitlement_denied`  | Include `license_id` (hashed) and reason     |
| Scanner image untrusted | 403  | `release_untrusted`   | Include digest and required identity         |
| Plan throttle           | 429  | `plan_throttled`      | Include limits and `Retry-After`             |
| Artifact too large      | 413  | `artifact_too_large`  | Include cap                                  |
| Fulcio/KMS down         | 503  | `signing_unavailable` | Retry‑After with jitter                      |

---

## 16) Deployment & HA

* Run ≥ 2 replicas; front with L7 LB; **sticky** not required.
* Redis for replay/quota caches (HA).
* Audit sink (Mongo/Postgres) in primary region; asynchronous write with local fallback buffer.
* Fulcio/KMS clients configured with retries/backoff; circuit breakers.

---

## 17) Implementation notes

* **.NET 10** minimal API + Kestrel mTLS; custom DPoP middleware; JWT/JWKS cache.
* **Cosign verification** via sigstore libraries; Referrers queries over registry API with retries.
* **DSSE** via in‑toto libs; canonical JSON writer for predicates.
* **Backpressure** paths: refuse at auth/quota stages before any expensive network calls.

---

## 18) Examples (wire)

**Request (free plan; expect throttle if burst):**

```http
POST /api/v1/signer/sign/dsse HTTP/1.1
Authorization: DPoP <JWT>
DPoP: <proof>
Content-Type: application/json

{ ...body as above... }
```

**Error (release untrusted):**

```json
{
  "type": "https://stella-ops.org/problems/release_untrusted",
  "title": "Scanner image not signed by StellaOps",
  "status": 403,
  "detail": "sha256:abcd... not in trusted keyring",
  "instance": "urn:audit:a7c9e3f2-..."
}
```

---

## 19) Roadmap

* **Key Transparency**: optional publication of Signer’s *own* certs to a KT log.
* **Attested Build**: SLSA‑style provenance for Signer container itself, checked at startup.
* **FIPS mode**: enforce `ES256` + KMS/HSM only; disallow Ed25519.
* **Dual attestation**: optional immediate push to **Attestor** (sync mode) with timeout budget, returning Rekor UUID inline.