Skip to content

Commit e0a44c1

Browse files
frankkilcomminsfrankkilcommins
committed
chore(spec): fix formatting
1 parent cf217c5 commit e0a44c1

2 files changed

Lines changed: 33 additions & 28 deletions

File tree

‎custom-words.txt‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,8 +5,10 @@ ARAX
55
arax
66
Arazzo
77
Auth
8+
dpop
89
Flesch
910
HATEOAS
11+
hoba
1012
JAIRF
1113
Jentic
1214
Kilcommins
@@ -15,4 +17,7 @@ llm
1517
llms
1618
opid
1719
parsable
20+
PKCE
21+
privatetoken
1822
Redocly
23+
ROPC

‎docs/specification/spec.md‎

Lines changed: 28 additions & 28 deletions
Original file line numberDiff line numberDiff line change
@@ -712,8 +712,8 @@ This value is NOT the same as “operations that declare security”, it reflect
712712
As a guiding principle, an operation SHOULD be classified as a _sensitive operation_ if any of the following are true:
713713

714714
- it performs a state changing action
715-
- uses HTTP methods such as: `POST`, `PUT`, `PATCH`, `DELETE`
716-
- has summaries/descriptions which suggest state change (e.g., "approve", "update", "assign", "create", "cancel"), even if HTTP verb is misused
715+
- uses HTTP methods such as: `POST`, `PUT`, `PATCH`, `DELETE`
716+
- has summaries/descriptions which suggest state change (e.g., "approve", "update", "assign", "create", "cancel"), even if HTTP verb is misused
717717
- it accesses or returns sensitive or personal data (customer records, user profiles, payment data, or any OpenAPI Schema Object containing detected PII fields)
718718
- it performs privileged or administrative actions
719719
- it exposes operational or system-level behaviours (configuration management details, system logs, workflow executions)
@@ -736,31 +736,31 @@ auth_strength = safe_divide(sum(strength_scores), count(schemes))
736736
The following table outlines the `auth_strength` scoring weights:
737737

738738
| Scheme Type | Description | Example | Strength | Rationale |
739-
| ---- | ---- | ----------- | ------- | -------------------- |
740-
| **none** | No authentication mechanism | no `security:` block | **0.00** | Unsafe for sensitive APIs; permitted only when no sensitive ops exist. |
741-
| **http / basic** | Base64 user:pass | `scheme: basic` | **0.10** | Plaintext credentials; weak per RFC7617. |
742-
| **http / oauth** | OAuth 1.0 | `scheme: oauth` | **0.20** | Deprecated, complex, insecure signature model. |
743-
| **http / digest** | Digest Access Auth | `scheme: digest` | **0.20** | Outdated; vulnerable despite hashing. |
744-
| **apiKey (query)** | API key in query param | `in: query` | **0.15** | High leakage risk (logs, proxies, URLs). |
745-
| **apiKey (header/cookie)** | API key passed in header/cookie | `in: header` | **0.50** | Common pattern but lacks scoping/rotation. |
746-
| **http / scram-sha-1** | SCRAM using SHA-1 | `scheme: scram-sha-1` | **0.25** | SHA-1 deprecated; limited security. |
747-
| **http / negotiate** | Kerberos/NTLM | `scheme: negotiate` | **0.35** | Violates HTTP semantics; legacy enterprise auth. |
748-
| **http / bearer (opaque)** | Bearer token without format | `scheme: bearer` | **0.60** | Strength depends entirely on distribution. |
749-
| **http / vapid** | WebPush VAPID | `scheme: vapid` | **0.60** | Similar risk to opaque bearer. |
750-
| **http / scram-sha-256** | SCRAM using SHA-256 | `scheme: scram-sha-256` | **0.65** | More secure, but still password-based. |
751-
| **http / bearer (JWT)** | Signed JWT | `bearerFormat: JWT` | **0.75** | Cryptographically verifiable tokens; supports scopes/claims. |
752-
| **http / privatetoken** | Privacy Pass | `scheme: privatetoken` | **0.75** | Strong cryptographic identity. |
753-
| **http / hoba** | HTTP Origin-Bound Auth | `scheme: hoba` | **0.80** | Client-bound cryptographic identity. |
754-
| **http / concealed** | Concealed auth scheme | `scheme: concealed` | **0.85** | Modern, privacy-preserving authentication. |
755-
| **http / dpop** | Proof-of-possession | `scheme: dpop` | **0.90** | Prevents token replay; strong guarantees. |
756-
| **http / gnap** | GNAP framework | `scheme: gnap` | **0.90** | Modern successor to OAuth; strong architecture. |
757-
| **http / mutual** | HTTP-level mutual authentication | `scheme: mutual` | **0.95** | Cryptographically bound identity. |
758-
| **oauth2 / password** | ROPC | flow: password | **0.30** | Deprecated; weak; violates least-privilege. |
759-
| **oauth2 / implicit** | Browser implicit | flow: implicit | **0.35** | Deprecated; token exposure vulnerability. |
760-
| **oauth2 / clientCredentials** | Server-to-server | flow: clientCredentials | **0.85** | Strong; scoped; widely recommended. |
761-
| **oauth2 / authorizationCode (PKCE)** | Best practice | flow: authorizationCode | **0.90** | Modern standard; strong protection. |
762-
| **openIdConnect** | OIDC Discovery/JWKs | type: openIdConnect | **1.00** | Gold standard for identity-bound access. |
763-
| **mutualTLS** | Client certificates | type: mutualTLS | **1.00** | Hardware-backed identity; strongest available. |
739+
| ----------- | ----------- | ------- | -------- | --------- |
740+
| `none` | No authentication mechanism | no `security:` block | `0.00` | Unsafe for sensitive APIs; permitted only when `sensitive_ops_expected = 0`. |
741+
| `http / basic` | Base64 user:pass | `scheme: basic` | `0.10` | Plaintext credentials; easily leaked ([RFC7617](https://tools.ietf.org/html/rfc7617)). |
742+
| `http / oauth` | OAuth 1.0 | `scheme: oauth` | `0.20` | Deprecated; insecure signature model ([RFC5849](https://tools.ietf.org/html/rfc5849)). |
743+
| `http / digest` | Digest Access Auth | `scheme: digest` | `0.20` | Outdated; limited protection ([RFC7616](https://tools.ietf.org/html/rfc7616)). |
744+
| `apiKey (query)` | API key in query string | `in: query` | `0.15` | Very high leakage risk (logs, proxies, URLs). |
745+
| `apiKey (header/cookie)` | API key in header or cookie | `in: header` | `0.50` | Moderate security; lacks identity, scoping, or rotation controls. |
746+
| `http / scram-sha-1` | SCRAM with SHA-1 | `scheme: scram-sha-1` | `0.25` | Uses deprecated SHA-1 hashing ([RFC7804](https://tools.ietf.org/html/rfc7804)). |
747+
| `http / negotiate` | Kerberos/NTLM | `scheme: negotiate` | `0.35` | Legacy; violates HTTP semantics ([RFC4559](https://tools.ietf.org/html/rfc4559)). |
748+
| `http / bearer (opaque)` | Opaque bearer token | `scheme: bearer` | `0.60` | Security depends entirely on token distribution ([RFC6750](https://tools.ietf.org/html/rfc6750)). |
749+
| `http / vapid` | WebPush VAPID | `scheme: vapid` | `0.60` | Token model similar to bearer; moderate trust ([RFC8292](https://tools.ietf.org/html/rfc8292)). |
750+
| `http / scram-sha-256` | SCRAM with SHA-256 | `scheme: scram-sha-256` | `0.65` | Modern and stronger, still password-based ([RFC7804](https://tools.ietf.org/html/rfc7804)). |
751+
| `http / bearer (JWT)` | Signed JWT bearer token | `bearerFormat: JWT` | `0.75` | Cryptographically verifiable claims; supports scopes. |
752+
| `http / privatetoken` | Privacy Pass | `scheme: privatetoken` | `0.75` | Strong privacy-preserving cryptographic identity ([RFC9577](https://tools.ietf.org/html/rfc9577)). |
753+
| `http / hoba` | HTTP Origin-Bound Authentication | `scheme: hoba` | `0.80` | Asymmetric client-bound authentication ([RFC7486](https://tools.ietf.org/html/rfc7486)). |
754+
| `http / concealed` | Concealed HTTP authentication | `scheme: concealed` | `0.85` | Modern, high-assurance privacy-preserving authentication ([RFC9729](https://tools.ietf.org/html/rfc9729)). |
755+
| `http / dpop` | Demonstration of Proof-of-Possession | `scheme: dpop` | `0.90` | Prevents replay; binds token to client ([RFC9449](https://tools.ietf.org/html/rfc9449)). |
756+
| `http / gnap` | GNAP framework | `scheme: gnap` | `0.90` | Modern alternative to OAuth 2.0 ([RFC9635](https://tools.ietf.org/html/rfc9635)). |
757+
| `http / mutual` | HTTP Mutual Authentication | `scheme: mutual` | `0.95` | Cryptographically binding client/server identities ([RFC8120](https://tools.ietf.org/html/rfc8120)). |
758+
| `oauth2 / password` | Resource Owner Password Credentials | `flow: password` | `0.30` | Deprecated; violates least-privilege; insecure. |
759+
| `oauth2 / implicit` | Browser implicit flow | `flow: implicit` | `0.35` | Deprecated; exposes tokens via redirects. |
760+
| `oauth2 / clientCredentials` | Server-to-server | `flow: clientCredentials` | `0.85` | Strong, scoped, recommended for machine-to-machine. |
761+
| `oauth2 / authorizationCode (PKCE)` | Best practice auth flow | `flow: authorizationCode` | `0.90` | Most secure OAuth2 flow; protects public clients. |
762+
| `openIdConnect` | OIDC Discovery + JWKs | `type: openIdConnect` | `1.00` | Gold-standard identity-bound access. |
763+
| `mutualTLS` | Client TLS certificates | `type: mutualTLS` | `1.00` | Hardware-backed identity; strongest available. |
764764

765765

766766
If no security schemes are defined, auth_strength MUST return `1.0` (not applicable—no schemes to evaluate).
@@ -1362,7 +1362,7 @@ Gating rules MUST override or constrain dimension scores to ensure safety and co
13621362
They MUST be applied immediately before readiness-level classification.
13631363

13641364
| Condition | Effect | Rationale |
1365-
|-----------|--------|-----------|
1365+
| --------- | ------ | --------- |
13661366
| Foundational Compliance score < 40 | API MUST be classified as Level 0 ("Non-Compliant") | If the API cannot be structurally validated, no higher-order AI reasoning is safe or possible. |
13671367
| Hardcoded credentials detected | Security score MUST be capped at `20` | Hardcoded secrets represent an immediate, systemic security failure and cannot be compensated for by other strengths. |
13681368
| Sensitive operations lacking auth (internal) | Security score MUST be capped at `40` | Internal APIs may permit limited trust boundaries, but unauthenticated sensitive operations remain high-risk. |

0 commit comments

Comments
 (0)