@agent-ix/spec-objects-security 0.4.0

package/skeletons/audit_finding.md

@@ -0,0 +1,25 @@
+---
+id: FIND-001
+title: "Session store reachable with eval privileges"
+type: audit_finding
+---
+<!-- audit_finding authoring skeleton (spec-objects-security). Fill every part
+     with substantive content. Contract (manifest body_extraction asserts):
+     - Frontmatter MUST carry id, title, type (type:
+       audit_finding).
+     - A "Recommendation" section MUST state the remediation recommendation. -->
+# [FIND-001] Session store reachable with eval privileges
+
+Q2 security audit finding: the auth service connects to the session store
+(ASSET-001) with a credential that retains `EVAL`/`SCRIPT` privileges,
+unnecessarily exposing the Lua sandbox surface of VULN-001 to any service
+compromise. Severity high; affected component is the shared Redis ACL profile.
+
+## Recommendation
+
+Upgrade the session store to a release patched for CVE-2024-31449, then
+replace the shared ACL profile with a least-privilege profile that removes
+`EVAL`, `EVALSHA` and `SCRIPT` for application credentials. Verify with an
+integration test that script commands are rejected, and re-scan the cluster.
+Target closure within 30 days; interim compensating control is the mTLS
+restriction at BOUND-001.

package/skeletons/auth_flow.md

@@ -0,0 +1,31 @@
+---
+id: AUTHFLOW-001
+title: "Tenant user login via OIDC authorization code flow"
+type: auth_flow
+---
+<!-- auth_flow authoring skeleton (spec-objects-security). Fill every part with
+     substantive content. Contract (manifest body_extraction asserts):
+     - Frontmatter MUST carry id, title, type (type: auth_flow).
+     - A "Flow" section MUST carry a ```mermaid code block describing the flow. -->
+# [AUTHFLOW-001] Tenant user login via OIDC authorization code flow
+
+Interactive browser login for Atlas tenant users. The platform delegates
+authentication to the tenant's OIDC identity provider using the authorization
+code flow with PKCE, then establishes a first-party session cookie.
+
+## Flow
+
+```mermaid
+sequenceDiagram
+    participant Browser
+    participant AtlasApp
+    participant IdP
+    Browser->>AtlasApp: GET /login
+    AtlasApp->>Browser: 302 to IdP authorize endpoint with PKCE challenge
+    Browser->>IdP: GET /authorize with client_id and code_challenge
+    IdP->>Browser: 302 back with authorization code
+    Browser->>AtlasApp: GET /callback with code and state
+    AtlasApp->>IdP: POST /token with code and code_verifier
+    IdP->>AtlasApp: ID token plus access and refresh tokens
+    AtlasApp->>Browser: Set __Host-atlas_session cookie and redirect
+```

package/skeletons/control.md

@@ -0,0 +1,24 @@
+---
+id: CTRL-001
+title: "Refresh token rotation with reuse detection"
+type: control
+---
+<!-- control authoring skeleton (spec-objects-security). Fill every part with
+     substantive content. Contract (manifest body_extraction asserts):
+     - Frontmatter MUST carry id, title, type (type: control).
+     - A "Mappings" section MUST map the control to threats, risks and
+       standards it addresses. -->
+# [CTRL-001] Refresh token rotation with reuse detection
+
+Every refresh-token exchange invalidates the presented token and issues a new
+one bound to the same grant family. Presenting an already-rotated token marks
+the whole family compromised: all descendants are revoked, the session is
+terminated, and a `token.reuse.detected` audit event fires.
+
+## Mappings
+
+- Mitigates THREAT-001 (stolen refresh token replay)
+- Reduces RISK-001 likelihood from medium to low
+- Implements OAuth 2.0 Security BCP (RFC 9700) refresh-token rotation guidance
+- Maps to OWASP ASVS v4 §3.5.2 and NIST SP 800-63B §7.1 session binding
+- Verified by integration test IT-001 (manifest activation roundtrip suite)

package/skeletons/cors_policy.md

@@ -0,0 +1,24 @@
+---
+id: CORS-001
+title: "Atlas public API CORS policy"
+type: cors_policy
+---
+<!-- cors_policy authoring skeleton (spec-objects-security). Fill every part
+     with substantive content. Contract (manifest body_extraction asserts):
+     - Frontmatter MUST carry id, title, type (type:
+       cors_policy).
+     - An "Origins" section MUST enumerate the allowed origins and rules. -->
+# [CORS-001] Atlas public API CORS policy
+
+Browser cross-origin policy enforced by the API gateway for `api.atlas.example`.
+Credentials are only honored for first-party app origins; integration origins
+get token-based access without cookies.
+
+## Origins
+
+- `https://app.atlas.example` — first-party web client; credentials allowed
+- `https://admin.atlas.example` — operator console; credentials allowed
+- `https://*.integrations.atlas.example` — sandboxed integration iframes;
+  credentials disallowed, `Authorization` header only
+- All other origins are denied; no wildcard `*` is ever emitted, and preflight
+  responses are capped at `Access-Control-Max-Age: 600`

package/skeletons/csrf_token.md

@@ -0,0 +1,19 @@
+---
+id: CSRF-001
+title: "Atlas web CSRF token"
+type: csrf_token
+rotation_window: 30m
+---
+<!-- csrf_token authoring skeleton (spec-objects-security). Fill every part with
+     substantive content. Contract (manifest body_extraction asserts):
+     - Frontmatter MUST carry id, title, type (type:
+       csrf_token) and rotation_window (how often a fresh token is issued). -->
+# [CSRF-001] Atlas web CSRF token
+
+Double-submit CSRF token protecting all state-changing requests from the Atlas
+web client. The server issues an HMAC-signed token bound to the session id
+(SESSION-001); the client echoes it in the `X-Atlas-CSRF` header and the
+middleware rejects any mutation where header and cookie values disagree. A
+fresh token is minted every `30m` rotation window and on every login or
+privilege elevation, with the previous token honored for one overlapping
+window to avoid breaking in-flight forms.

package/skeletons/data_classification.md

@@ -0,0 +1,25 @@
+---
+id: CLASS-001
+title: "Confidential — tenant PII"
+type: data_classification
+---
+<!-- data_classification authoring skeleton (spec-objects-security). Fill every
+     part with substantive content. Contract (manifest body_extraction asserts):
+     - Frontmatter MUST carry id, title, type (type:
+       data_classification).
+     - A "Handling" section MUST state the handling requirements for the class. -->
+# [CLASS-001] Confidential — tenant PII
+
+Classification applied to tenant member profile data (names, email addresses,
+phone numbers) and any document flagged as containing personal data. Sits one
+level below `Restricted` (secrets and key material) in the Atlas scheme.
+
+## Handling
+
+- Encrypted at rest with the tenant DEK (KEY-001) and in transit via TLS 1.3.
+- Access requires an explicit permission grant; reads are recorded in the
+  audit stream as `pii.accessed` events.
+- Never written to application logs; log scrubbing rejects payloads matching
+  the PII field allowlist.
+- Exported only through the GDPR export pipeline, with tenant-admin approval.
+- Retention: deleted within 30 days of tenant offboarding or subject request.

package/skeletons/encryption_key.md

@@ -0,0 +1,18 @@
+---
+id: KEY-001
+title: "Tenant data encryption key"
+type: encryption_key
+algorithm: AES-256-GCM
+rotation: 90d
+---
+<!-- encryption_key authoring skeleton (spec-objects-security). Fill every part
+     with substantive content. Contract (manifest body_extraction asserts):
+     - Frontmatter MUST carry id, title, type (type:
+       encryption_key) and algorithm (the cipher); rotation gives the cadence. -->
+# [KEY-001] Tenant data encryption key
+
+Per-tenant data encryption key (DEK) protecting documents at rest in the Atlas
+object store. Each DEK is wrapped by the platform KMS root key and unwrapped
+only inside the storage service; plaintext keys never leave process memory.
+Rotation re-wraps the DEK on the `90d` cadence declared above without
+re-encrypting historical objects, which remain readable via key versioning.

package/skeletons/jwt_claim.md

@@ -0,0 +1,27 @@
+---
+id: CLAIM-001
+title: "tenant_id access-token claim"
+type: jwt_claim
+---
+<!-- jwt_claim authoring skeleton (spec-objects-security). Fill every part with
+     substantive content. Contract (manifest body_extraction asserts):
+     - Frontmatter MUST carry id, title, type (type:
+       jwt_claim).
+     - A "Schema" section MUST carry a ```json code block with the claim's
+       JSON Schema. -->
+# [CLAIM-001] tenant_id access-token claim
+
+Custom claim stamped into every Atlas access token at issuance. The policy
+engine uses it for row-level tenant isolation (see PERM-001); tokens without a
+valid `tenant_id` are rejected at the gateway before reaching any service.
+
+## Schema
+
+```json
+{
+  "title": "tenant_id",
+  "type": "string",
+  "format": "uuid",
+  "description": "UUID of the tenant the subject is acting within; immutable for the token lifetime"
+}
+```

package/skeletons/mfa_method.md

@@ -0,0 +1,19 @@
+---
+id: MFA-001
+title: "TOTP authenticator app"
+type: mfa_method
+kind: totp
+factor: possession
+---
+<!-- mfa_method authoring skeleton (spec-objects-security). Fill every part with
+     substantive content. Contract (manifest body_extraction asserts):
+     - Frontmatter MUST carry id, title, type (type:
+       mfa_method) and kind (the method kind); factor names the auth factor
+       class it provides. -->
+# [MFA-001] TOTP authenticator app
+
+Time-based one-time password second factor (RFC 6238) for Atlas operator and
+break-glass accounts. Secrets are 160-bit, provisioned via QR code over an
+authenticated session, and stored encrypted under KEY-001. Codes are 6 digits
+on a 30-second step with one step of clock skew accepted; ten single-use
+recovery codes are issued at enrollment for device-loss fallback.

package/skeletons/password_policy.md

@@ -0,0 +1,26 @@
+---
+id: PASSPOL-001
+title: "Atlas local-account password policy"
+type: password_policy
+---
+<!-- password_policy authoring skeleton (spec-objects-security). Fill every part
+     with substantive content. Contract (manifest body_extraction asserts):
+     - Frontmatter MUST carry id, title, type (type:
+       password_policy).
+     - A "Rules" section MUST enumerate the enforced password rules. -->
+# [PASSPOL-001] Atlas local-account password policy
+
+Applies to break-glass local accounts only; regular tenant users authenticate
+through their IdP (AUTHFLOW-001). Aligned with NIST SP 800-63B: length over
+composition, breach screening over forced rotation.
+
+## Rules
+
+- Minimum length 12 characters, maximum 128; all printable Unicode accepted
+- Candidate passwords are checked against the haveibeenpwned k-anonymity API
+  and rejected when previously breached
+- No mandatory periodic rotation; rotation is forced only on suspected
+  compromise
+- Hashing: argon2id with memory 64 MiB, iterations 3, parallelism 4
+- Rate limiting: 10 failed attempts per account per 15 minutes, then lockout
+  with audit event emission

package/skeletons/permission.md

@@ -0,0 +1,18 @@
+---
+id: PERM-001
+title: "Read tenant documents"
+type: permission
+resource: document
+verb: read
+---
+<!-- permission authoring skeleton (spec-objects-security). Fill every part with
+     substantive content. Contract (manifest body_extraction asserts):
+     - Frontmatter MUST carry id, title, type (type: permission).
+     - Frontmatter MUST carry resource and verb (the protected resource kind and
+       the action this permission grants on it). -->
+# [PERM-001] Read tenant documents
+
+Grants read access to `document` resources within the caller's tenant. Checked
+by the Atlas policy engine on every `GET /api/documents/*` request; the
+permission is satisfied only when the resource's `tenant_id` matches the
+caller's `tenant_id` claim.

package/skeletons/policy.md

@@ -0,0 +1,25 @@
+---
+id: POL-001
+title: "Access token lifetime policy"
+type: policy
+---
+<!-- policy authoring skeleton (spec-objects-security). Fill every part with
+     substantive content. Contract (manifest body_extraction asserts):
+     - Frontmatter MUST carry id, title, type (type: policy).
+     - A "Policy" section MUST state the normative policy text. -->
+# [POL-001] Access token lifetime policy
+
+Platform-wide policy governing bearer token lifetimes for Atlas first-party
+and integration clients, owned by the security council.
+
+## Policy
+
+- Access tokens SHALL expire no later than 15 minutes after issuance.
+- Refresh tokens SHALL be single-use and rotated on every exchange (CTRL-001),
+  with an absolute family lifetime of 30 days.
+- Integration tokens issued for SCOPE-001 SHALL be bound to the requesting
+  client via DPoP or mTLS sender constraint.
+- Token lifetimes SHALL NOT be extended per tenant without a documented risk
+  acceptance referencing the affected risk register entries (e.g. RISK-001).
+- Violations surface as audit findings (FIND-001 family) and block release
+  until remediated or formally accepted.

package/skeletons/risk.md

@@ -0,0 +1,20 @@
+---
+id: RISK-001
+title: "Tenant account takeover via token theft"
+type: risk
+likelihood: medium
+impact: high
+---
+<!-- risk authoring skeleton (spec-objects-security). Fill every part with
+     substantive content. Contract (manifest body_extraction asserts):
+     - Frontmatter MUST carry id, title, type (type: risk),
+       likelihood and impact (qualitative ratings driving the risk score). -->
+# [RISK-001] Tenant account takeover via token theft
+
+Business risk that an attacker realizes THREAT-001 and operates inside a
+tenant with the victim's permissions, exposing Confidential PII (CLASS-001)
+and enabling data exfiltration through the public API. Likelihood is rated
+medium given commodity infostealer malware; impact is high because a single
+takeover crosses into regulated personal data. Primary treatment is CTRL-001;
+residual risk after rotation and reuse detection is accepted at low/high and
+reviewed quarterly by the security council.

package/skeletons/role.md

@@ -0,0 +1,21 @@
+---
+id: ROLE-001
+title: "Tenant Auditor role"
+type: role
+---
+<!-- role authoring skeleton (spec-objects-security). Fill every part with
+     substantive content. Contract (manifest body_extraction asserts):
+     - Frontmatter MUST carry id, title, type (type: role).
+     - A "Permissions" section MUST list the permissions bound to the role. -->
+# [ROLE-001] Tenant Auditor role
+
+Read-only compliance role assigned to external auditors invited into a tenant.
+Members can inspect configuration and audit trails but can never mutate state
+or read secret material.
+
+## Permissions
+
+- PERM-001 — `document:read` within the tenant
+- `audit_log:read` — query the tenant's audit event stream
+- `policy:read` — view security policies in effect for the tenant
+- `member:list` — enumerate tenant members and their role bindings

package/skeletons/scope.md

@@ -0,0 +1,20 @@
+---
+id: SCOPE-001
+title: "documents:read OAuth scope"
+type: scope
+---
+<!-- scope authoring skeleton (spec-objects-security). Fill every part with
+     substantive content. Contract (manifest body_extraction asserts):
+     - Frontmatter MUST carry id, title, type (type: scope).
+     - A "Grants" section MUST list the permissions this scope confers. -->
+# [SCOPE-001] documents:read OAuth scope
+
+OAuth 2.0 scope requested by third-party integrations that need read-only
+access to a tenant's document library through the Atlas public API.
+
+## Grants
+
+- PERM-001 — read tenant documents (`document:read`)
+- Listing document metadata via `GET /api/documents`
+- Downloading rendered document content via `GET /api/documents/{id}/content`
+- Excludes all write verbs; mutations require the separate `documents:write` scope

package/skeletons/secret.md

@@ -0,0 +1,25 @@
+---
+id: SECRET-001
+title: "Atlas OIDC client secret"
+type: secret
+---
+<!-- secret authoring skeleton (spec-objects-security). Fill every part with
+     substantive content. Contract (manifest body_extraction asserts):
+     - Frontmatter MUST carry id, title, type (type: secret).
+     - A "Rotation" section MUST describe how and how often the secret rotates. -->
+# [SECRET-001] Atlas OIDC client secret
+
+Confidential client secret used by the Atlas backend to authenticate at the
+tenant IdP token endpoint during the authorization code exchange. Stored in
+Vault at `secret/atlas/oidc/client-secret`; never present in environment files
+or images.
+
+## Rotation
+
+- Rotated every 90 days by the `secret-rotator` job, which registers a new
+  secret with the IdP before revoking the old one.
+- Dual-secret overlap window of 24 hours so in-flight token exchanges complete
+  against either value.
+- Emergency rotation is triggered manually via `atlasctl secrets rotate
+  oidc-client` and completes in under 5 minutes.
+- Every rotation emits an `secret.rotated` audit event (AUDIT-001 family).

package/skeletons/session_config.md

@@ -0,0 +1,24 @@
+---
+id: SESSION-001
+title: "Atlas web session configuration"
+type: session_config
+---
+<!-- session_config authoring skeleton (spec-objects-security). Fill every part
+     with substantive content. Contract (manifest body_extraction asserts):
+     - Frontmatter MUST carry id, title, type (type:
+       session_config).
+     - A "Settings" section MUST enumerate the effective session parameters. -->
+# [SESSION-001] Atlas web session configuration
+
+Server-side session established after AUTHFLOW-001 completes. Session state
+lives in the session store (ASSET-001); the browser holds only an opaque
+identifier.
+
+## Settings
+
+- Cookie name: `__Host-atlas_session` (Secure, HttpOnly, SameSite=Lax, Path=/)
+- Idle timeout: 30 minutes, sliding on authenticated requests
+- Absolute lifetime: 12 hours, after which re-authentication is required
+- Session identifier: 256-bit random value, regenerated on login and on
+  privilege elevation
+- Concurrent session cap: 5 per user; the oldest session is evicted on overflow

package/skeletons/threat.md

@@ -0,0 +1,19 @@
+---
+id: THREAT-001
+title: "Stolen refresh token replay"
+type: threat
+stride_category: Spoofing
+vector: "exfiltrated refresh token replayed from attacker infrastructure"
+---
+<!-- threat authoring skeleton (spec-objects-security). Fill every part with
+     substantive content. Contract (manifest body_extraction asserts):
+     - Frontmatter MUST carry id, title, type (type: threat),
+       stride_category (STRIDE class) and vector (the attack vector). -->
+# [THREAT-001] Stolen refresh token replay
+
+An attacker who exfiltrates a refresh token (malware on the user device, log
+leakage, or proxy compromise) replays it against the token endpoint to mint
+fresh access tokens and impersonate the user across tenant APIs. Detection is
+hard because requests are well-formed; mitigation relies on refresh token
+rotation with reuse detection (CTRL-001) and the trust boundary controls in
+BOUND-001. Realized risk is tracked as RISK-001.

package/skeletons/trust_boundary.md

@@ -0,0 +1,26 @@
+---
+id: BOUND-001
+title: "Edge to auth-service trust boundary"
+type: trust_boundary
+---
+<!-- trust_boundary authoring skeleton (spec-objects-security). Fill every part
+     with substantive content. Contract (manifest body_extraction asserts):
+     - Frontmatter MUST carry id, title, type (type:
+       trust_boundary).
+     - A "Boundary" section MUST carry a ```mermaid code block drawing the
+       boundary between zones. -->
+# [BOUND-001] Edge to auth-service trust boundary
+
+Separates the untrusted internet, the DMZ-hosted API gateway, and the trusted
+private subnet where the Atlas auth service and session store run. Everything
+crossing inward is re-authenticated: the gateway terminates TLS and the auth
+service only accepts mTLS connections from the gateway.
+
+## Boundary
+
+```mermaid
+flowchart LR
+    Browser["Tenant browser (untrusted)"] -->|HTTPS| Gateway["API gateway (DMZ)"]
+    Gateway -->|mTLS| AuthSvc["Auth service (trusted subnet)"]
+    AuthSvc -->|private VPC peering| SessionDB[("Session store")]
+```

package/skeletons/vulnerability.md

@@ -0,0 +1,21 @@
+---
+id: VULN-001
+title: "Session store affected by lua sandbox escape"
+type: vulnerability
+cve_id: CVE-2024-31449
+severity: high
+---
+<!-- vulnerability authoring skeleton (spec-objects-security). Fill every part
+     with substantive content. Contract (manifest body_extraction asserts):
+     - Frontmatter MUST carry id, title, type (type:
+       vulnerability) and severity; cve_id links the public advisory when one
+       exists. -->
+# [VULN-001] Session store affected by lua sandbox escape
+
+The Redis instance backing the Atlas session store (ASSET-001) runs a version
+affected by CVE-2024-31449, where an authenticated client can craft a Lua
+script that escapes the sandbox and executes arbitrary code. Exploitation
+requires script-eval privileges inside the private subnet, so exposure is
+limited by BOUND-001, but a compromised service credential would yield full
+session-store control. Remediation: upgrade to a patched Redis release and
+disable `EVAL` for application credentials; tracked to closure in FIND-001.