@agent-ix/spec-objects-security 0.5.0 → 0.9.0

package/skeletons/audit_finding.md

@@ -1,25 +1,29 @@
 ---
 id: FIND-001
-title: "Session store reachable with eval privileges"
+title: "MissingTokenRotation"
 type: audit_finding
+object: 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.
+<!-- audit_finding authoring skeleton (spec-objects-security). Fill every section with
+     substantive content. Contract (manifest body_extraction asserts):
+     - Frontmatter MUST carry id, title, type: audit_finding,
+       object: audit_finding.
+     - "## Recommendation" (H2, required): what the auditor asks for.
+     - "## Properties" (H2): the typed declaration. AuditFinding.json
+       requires a `status` row, so an untriaged finding is refused. -->
+# [FIND-001] MissingTokenRotation
 
 ## 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.
+Enable refresh-token rotation with reuse detection on every tenant IdP
+integration, and fail the release gate while any integration is without it.
+Re-audit thirty days after the change lands.
+
+## Properties
+
+| Field | Type | Multiplicity | Constraints |
+|---|---|---|---|
+| finding_id | UUID | 1..1 | identity |
+| status | String | 1..1 | minLength: 1 |
+| observed_at | Timestamp | 1..1 |  |
+| traced_risk | TenantDataExfiltration | 0..1 |  |

package/skeletons/auth_flow.md

@@ -1,31 +1,66 @@
 ---
-id: AUTHFLOW-001
-title: "Tenant user login via OIDC authorization code flow"
+id: AUTH-001
+title: "AuthorizationCodeWithPkce"
 type: auth_flow
+object: auth_flow
 ---
-<!-- auth_flow authoring skeleton (spec-objects-security). Fill every part with
+<!-- auth_flow authoring skeleton (spec-objects-security). Fill every section 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.
+     - Frontmatter MUST carry id, title, type: auth_flow, object: auth_flow.
+     - "## Flow" (H2, required) holds a fenced `mermaid` diagram.
+     - "## Operations" (H2): one `### <name>` per exchange, an optional param
+       table, a `Returns: <Type>[<multiplicity>]` line and optional Pre:/Post:
+       lines. AuthFlow.json requires at least one operation — a flow is its
+       exchanges. -->
+# [AUTH-001] AuthorizationCodeWithPkce
 
 ## 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
+  participant U as User agent
+  participant C as Client
+  participant A as Authorization server
+  C->>A: authorize with code_challenge
+  A->>U: prompt and consent
+  U->>C: authorization code
+  C->>A: exchange code with code_verifier
+  A->>C: access token and refresh token
 ```
+
+## Operations
+
+The exchanges this flow performs. Each operation owns one `### <name>`
+heading; the param table is the typed declaration of its inputs.
+
+### authorize
+
+Start the flow and obtain an authorization code.
+
+| Param | Type | Multiplicity | Constraints |
+|---|---|---|---|
+| code_challenge | String | 1..1 | minLength: 43 |
+| redirect_uri | String | 1..1 | minLength: 1 |
+
+Returns: String[1..1]
+
+### exchange_code
+
+Exchange the code and verifier for a token pair.
+
+| Param | Type | Multiplicity | Constraints |
+|---|---|---|---|
+| code | String | 1..1 | minLength: 1 |
+| code_verifier | String | 1..1 | minLength: 43 |
+
+Returns: Boolean[1..1]
+
+### refresh
+
+Rotate the grant family and issue a fresh token pair.
+
+| Param | Type | Multiplicity | Constraints |
+|---|---|---|---|
+| presented_token_locator | String | 1..1 | minLength: 1 |
+
+Returns: Boolean[1..1]

package/skeletons/control.md

@@ -1,24 +1,53 @@
 ---
 id: CTRL-001
-title: "Refresh token rotation with reuse detection"
+title: "RefreshTokenRotation"
 type: control
+object: control
 ---
-<!-- control authoring skeleton (spec-objects-security). Fill every part with
+<!-- control authoring skeleton (spec-objects-security). Fill every section 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.
+     - Frontmatter MUST carry id, title, type: control, object: control.
+     - "## Mappings" (H2, required): the threats, risks and standards this
+       control addresses.
+     - "## Properties" (H2): Control.json requires an `effectiveness` row, so
+       effectiveness is always stated and never assumed.
+     - "## Invariants" (H2): Control.json requires at least one clause. -->
+# [CTRL-001] RefreshTokenRotation
 
 ## 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)
+- Mitigates RefreshTokenReplay (stolen refresh token replay).
+- Reduces TenantDataExfiltration likelihood from possible to unlikely.
+- 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.
+
+## Properties
+
+| Field | Type | Multiplicity | Constraints |
+|---|---|---|---|
+| control_id | UUID | 1..1 | identity |
+| effectiveness | String | 1..1 | minLength: 1 |
+| owner | String | 1..1 | minLength: 1 |
+| last_assessed_at | Timestamp | 1..1 |  |
+
+## Invariants
+
+The clauses this control enforces. Each clause owns one `ocl` fence under its
+own `### <clauseId>` heading; the fence text is carried verbatim and never
+evaluated here.
+
+### EveryExchangeInvalidatesThePresentedToken
+
+```ocl
+context RefreshTokenRotation
+inv EveryExchangeInvalidatesThePresentedToken:
+  self.effectiveness <> 'not_assessed' implies self.last_assessed_at->notEmpty()
+```
+
+### ReuseRevokesTheWholeFamily
+
+```ocl
+context RefreshTokenRotation
+inv ReuseRevokesTheWholeFamily:
+  self.owner->notEmpty()
+```

package/skeletons/cors_policy.md

@@ -1,24 +1,40 @@
 ---
 id: CORS-001
-title: "Atlas public API CORS policy"
+title: "TenantApiCorsPolicy"
 type: cors_policy
+object: 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.
+<!-- cors_policy authoring skeleton (spec-objects-security). Fill every section with
+     substantive content. Contract (manifest body_extraction asserts):
+     - Frontmatter MUST carry id, title, type: cors_policy,
+       object: cors_policy.
+     - "## Origins" (H2, required): the allowed origins.
+     - "## Invariants" (H2): CorsPolicy.json requires at least one clause. -->
+# [CORS-001] TenantApiCorsPolicy
 
 ## 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`
+- `https://app.example.com` — the first-party tenant console.
+- `https://*.tenant.example.com` — per-tenant vanity hosts, exact-suffix matched.
+- No wildcard origin, and no origin is echoed back unvalidated.
+
+## Invariants
+
+The clauses this policy asserts. Each clause owns one `ocl` fence under its
+own `### <clauseId>` heading.
+
+### NoWildcardOrigin
+
+```ocl
+context TenantApiCorsPolicy
+inv NoWildcardOrigin:
+  self.allowed_origins->excludes('*')
+```
+
+### CredentialsNeverWithWildcard
+
+```ocl
+context TenantApiCorsPolicy
+inv CredentialsNeverWithWildcard:
+  self.allow_credentials implies self.allowed_origins->size() > 0
+```

package/skeletons/csrf_token.md

@@ -1,19 +1,23 @@
 ---
 id: CSRF-001
-title: "Atlas web CSRF token"
+title: "SessionAntiForgeryToken"
 type: csrf_token
-rotation_window: 30m
+object: csrf_token
+rotation_window: PT30M
 ---
-<!-- csrf_token authoring skeleton (spec-objects-security). Fill every part with
+<!-- csrf_token authoring skeleton (spec-objects-security). Fill every section 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
+     - Frontmatter MUST carry id, title, type: csrf_token, object: csrf_token
+       and rotation_window.
+     - "## Properties" (H2): CsrfToken.json admits no field carrying a
+       default, so no token value appears in the declaration. -->
+# [CSRF-001] SessionAntiForgeryToken
 
-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.
+## Properties
+
+| Field | Type | Multiplicity | Constraints |
+|---|---|---|---|
+| token_id | UUID | 1..1 | identity |
+| locator | String | 1..1 | minLength: 1 |
+| bound_session_attribute | String | 1..1 | minLength: 1 |
+| rotation_window | Duration | 1..1 |  |

package/skeletons/data_classification.md

@@ -1,25 +1,30 @@
 ---
 id: CLASS-001
-title: "Confidential — tenant PII"
+title: "DataRestricted"
 type: data_classification
+object: 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.
+<!-- data_classification authoring skeleton (spec-objects-security). Fill every section with
+     substantive content. Contract (manifest body_extraction asserts):
+     - Frontmatter MUST carry id, title, type: data_classification,
+       object: data_classification.
+     - "## Handling" (H2, required): how data of this class is handled.
+     - "## Properties" (H2): the typed declaration. DataClassification.json
+       requires a `level` row. -->
+# [CLASS-001] DataRestricted
 
 ## 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.
+- Encrypted at rest with TenantDataEncryptionKey and in transit with TLS 1.3.
+- Never written to application logs, traces, or error payloads.
+- Exported only under ExportTenantData, and only to the owning tenant.
+- Deleted within the retention period once the tenant contract ends.
+
+## Properties
+
+| Field | Type | Multiplicity | Constraints |
+|---|---|---|---|
+| classification_id | UUID | 1..1 | identity |
+| level | String | 1..1 | minLength: 1 |
+| retention | Duration | 1..1 |  |
+| logging_permitted | Boolean | 1..1 |  |

package/skeletons/encryption_key.md

@@ -1,18 +1,25 @@
 ---
 id: KEY-001
-title: "Tenant data encryption key"
+title: "TenantDataEncryptionKey"
 type: encryption_key
+object: encryption_key
 algorithm: AES-256-GCM
-rotation: 90d
+rotation: P90D
 ---
-<!-- 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
+<!-- encryption_key authoring skeleton (spec-objects-security). Fill every section with
+     substantive content. Contract (manifest body_extraction asserts):
+     - Frontmatter MUST carry id, title, type: encryption_key,
+       object: encryption_key and algorithm; rotation is optional.
+     - "## Properties" (H2): the typed declaration. EncryptionKey.json admits
+       no field carrying a default, so key material is referenced, never held. -->
+# [KEY-001] TenantDataEncryptionKey
 
-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.
+## Properties
+
+| Field | Type | Multiplicity | Constraints |
+|---|---|---|---|
+| key_id | UUID | 1..1 | identity |
+| locator | String | 1..1 | minLength: 1 |
+| lifecycle | String | 1..1 | minLength: 1 |
+| key_length_bits | Integer | 1..1 | min: 256 |
+| rotation_period | Duration | 1..1 |  |

package/skeletons/jwt_claim.md

@@ -1,27 +1,38 @@
 ---
 id: CLAIM-001
-title: "tenant_id access-token claim"
+title: "TenantIdentifierClaim"
 type: jwt_claim
+object: jwt_claim
 ---
-<!-- jwt_claim authoring skeleton (spec-objects-security). Fill every part with
+<!-- jwt_claim authoring skeleton (spec-objects-security). Fill every section 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
+     - Frontmatter MUST carry id, title, type: jwt_claim, object: jwt_claim.
+     - "## Schema" (H2, required) holds a fenced `json` block. It is a
+       derived, human-facing view; the typed table is the authority.
+     - "## Properties" (H2): JwtClaim.json admits no field carrying a
+       default, so no claim value is written into the declaration. -->
+# [CLAIM-001] TenantIdentifierClaim
 
-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.
+## Properties
+
+| Field | Type | Multiplicity | Constraints |
+|---|---|---|---|
+| claim_id | UUID | 1..1 | identity |
+| claim_name | String | 1..1 | minLength: 1, maxLength: 32 |
+| value_type | String | 1..1 | minLength: 1 |
+| required_in_access_token | Boolean | 1..1 |  |
 
 ## Schema
 
 ```json
 {
-  "title": "tenant_id",
-  "type": "string",
-  "format": "uuid",
-  "description": "UUID of the tenant the subject is acting within; immutable for the token lifetime"
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://specs.agent-ix.dev/claims/tenant-identifier.schema.json",
+  "title": "TenantIdentifierClaim",
+  "type": "object",
+  "required": ["tid"],
+  "properties": {
+    "tid": { "type": "string", "format": "uuid" }
+  }
 }
 ```

package/skeletons/mfa_method.md

@@ -1,19 +1,25 @@
 ---
 id: MFA-001
-title: "TOTP authenticator app"
+title: "TimeBasedOneTimeCode"
 type: mfa_method
+object: mfa_method
 kind: totp
 factor: possession
 ---
-<!-- mfa_method authoring skeleton (spec-objects-security). Fill every part with
+<!-- mfa_method authoring skeleton (spec-objects-security). Fill every section 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
+     - Frontmatter MUST carry id, title, type: mfa_method, object: mfa_method
+       and kind; factor is optional.
+     - "## Properties" (H2): the typed declaration. MfaMethod.json admits no
+       field carrying a default, so no enrolment value can be embedded. -->
+# [MFA-001] TimeBasedOneTimeCode
 
-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.
+## Properties
+
+| Field | Type | Multiplicity | Constraints |
+|---|---|---|---|
+| method_id | UUID | 1..1 | identity |
+| factor_kind | String | 1..1 | minLength: 1 |
+| code_digits | Integer | 1..1 | min: 6, max: 8 |
+| step_period | Duration | 1..1 |  |
+| seed_locator | String | 1..1 | minLength: 1 |

package/skeletons/password_policy.md

@@ -1,26 +1,41 @@
 ---
-id: PASSPOL-001
-title: "Atlas local-account password policy"
+id: PWD-001
+title: "TenantPasswordPolicy"
 type: password_policy
+object: 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.
+<!-- password_policy authoring skeleton (spec-objects-security). Fill every section with
+     substantive content. Contract (manifest body_extraction asserts):
+     - Frontmatter MUST carry id, title, type: password_policy,
+       object: password_policy.
+     - "## Rules" (H2, required): the rules in prose.
+     - "## Invariants" (H2): PasswordPolicy.json requires at least one clause. -->
+# [PWD-001] TenantPasswordPolicy
 
 ## 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
+- At least 12 characters, with no composition rule beyond length.
+- Checked against the breached-password corpus at set time and at each login.
+- No forced periodic expiry; rotation is event-driven on suspected compromise.
+- Stored only as an Argon2id digest, never reversibly.
+
+## Invariants
+
+The clauses this policy asserts. Each clause owns one `ocl` fence under its
+own `### <clauseId>` heading.
+
+### MinimumLengthIsTwelve
+
+```ocl
+context TenantPasswordPolicy
+inv MinimumLengthIsTwelve:
+  self.minimum_length >= 12
+```
+
+### NoReversibleStorage
+
+```ocl
+context TenantPasswordPolicy
+inv NoReversibleStorage:
+  self.storage_scheme = 'argon2id'
+```

package/skeletons/permission.md

@@ -1,18 +1,24 @@
 ---
 id: PERM-001
-title: "Read tenant documents"
+title: "ExportTenantData"
 type: permission
-resource: document
-verb: read
+object: permission
+resource: "tenant/records"
+verb: export
 ---
-<!-- permission authoring skeleton (spec-objects-security). Fill every part with
+<!-- permission authoring skeleton (spec-objects-security). Fill every section 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
+     - Frontmatter MUST carry id, title, type: permission, object: permission,
+       resource (what is acted on) and verb (the action).
+     - "## Properties" (H2): the typed declaration. Permission.json forbids
+       `operations` and `relations`. -->
+# [PERM-001] ExportTenantData
 
-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.
+## Properties
+
+| Field | Type | Multiplicity | Constraints |
+|---|---|---|---|
+| permission_id | UUID | 1..1 | identity |
+| resource | String | 1..1 | minLength: 1 |
+| verb | String | 1..1 | minLength: 1 |
+| requires_reauthentication | Boolean | 1..1 |  |