Add CarrierAttestation API proposal

[hamr0]

What type of PR is this?

API proposal

What this PR does / why we need it:

Adds the filled API-proposal template for the CarrierAttestation API family: documentation/API proposals/APIProposal_CarrierAttestation.md.

The proposal is for a horizontal profile — "attested windowed disclosure" — rather than a new free-standing API. A predicate answer becomes a signed, nonce-bound, expiring boolean instead of the underlying raw value.

CAMARA already ships the precedents this completes:

• POST /retrieve-age-band (SimSwap v2.1.0) coarsens a raw timestamp into a band, because the raw value over-discloses.
• GET /device-phone-number (NumberVerification v2.1.0) takes no request body at all, deriving the line from the 3-legged access token.
• kyc-age-verification already ships a boolean age-threshold predicate.

The ask is to finish what those three started, catalog-wide. CarrierAttestation is filed as a new API family only for the residual no existing catalog API can be adopted into: agent-grade floor bundles and holder presentment.

Which issue(s) this PR fixes:

Fixes #330

Special notes for reviewers:

• Supporters is intentionally blank, per the template's own instruction that the Working Group populates it.
• Validated with operators: NO. Validated with real customers: NO. Stated plainly — no operator has reviewed this proposal. Lab validation is sandbox tier only (Orange Network APIs Playground).
• The proposal's own known limits are kept in the text on purpose, not smoothed over: Mode A retains the operator query log; economic scarcity is not uniqueness; the trust directory is a centralization point; MNP breaks naive tenure.
• Supporting material (proposal document with the full normative profile, a zero-dependency PoC, and an illustrative OpenAPI sketch) lives at https://github.com/hamr0/justabit — Apache 2.0, the author's own staging ground, not a CAMARA deliverable.

Changelog input

documentation/API proposals/APIProposal_CarrierAttestation.md

[linux-foundation-easycla]

The committers listed above are authorized under a signed CLA.

• ✅ login: hamr0 / name: hamr0 (87d36de)

[albertoramosmonagas]

Hi @hamr0, thank you for submitting this proposal. After reviewing the filing against the CAMARA API Proposal Template, the Project Charter, and the existing sub-project portfolio, here are my main comments.

1. Project Charter alignment. The "horizontal profile" framing does not map to a valid CAMARA sub-project type — the Charter requires a concrete API family with a defined YAML interface. Additionally, use case 2 (AI agent holder presentment / trust directory) describes east-west verifiable-credential infrastructure, which the Charter explicitly excludes. It needs to be dropped or reframed with a Charter justification.

2. Direct overlap with existing sub-projects. The overlap with KYC Age Verification and SimSwap is functional, not just inspirational. KYC Age Verification already returns a boolean predicate over an operator-held subscriber fact; SimSwap v2.1.0 age-band already covers the windowed swap recency pattern. The only delta in both cases is the signing wrapper — which brings us to point 3.

3. The signing layer belongs in Commonalities/ICM. CAMARA already defines request-side binding via DPoP (camara:bh, camara:qh) in the Security Interoperability Profile. If signed API responses are a valid CAMARA pattern, that decision and its format definition belong in Commonalities — where it would apply consistently to all existing and future sub-projects. Creating a new CarrierAttestation sub-project to own a signing layer on top of KYC Age Verification, SimSwap, and NumberVerification fragments governance and duplicates capability that is already there. The right vehicle is a Scope Enhancement on Commonalities, not a new sub-project.

CC: @camaraproject/commonalities_codeowners @camaraproject/identity-and-consent-management_codeowners

Recommended path forward:

1. Drop or reframe use case 2.
2. Consider resubmitting as Scope Enhancement requests on KYC Age Verification, SimSwap, and/or Commonalities.
3. Present at the next APIBacklog WG session to get early guidance and identify operator supporters.
4. Upload the OpenAPI sketch and carara-attested-windowed-disclosure.md as supporting materials directly on this issue.
5. Prepare a short deck for the WG session covering the problem, the revised use cases, the signing standard (SD-JWT / JOSE / W3C VC), and the Scope Enhancement path.

CC: @camaraproject/api-backlog_codeowners

[hamr0]

Thank you for the review — all three points are accepted.

1. Charter alignment: use case 2 (AI-agent holder presentment / trust directory) is withdrawn from CAMARA. It continues only as a separate IETF submission.
2. Overlap: accepted, and we found one more. Our own portfolio sweep turned up the Tenure API (POST /check-tenure → boolean tenureDateCheck, TSC-approved 2024-05-16). The filed template's "no overlap" statement was wrong on that point; corrected here.
3. Signing layer in Commonalities: accepted. We will resubmit as a Scope Enhancement targeting Commonalities, with SimSwap /check as the first adoption example. The delta is only the envelope: a JWS (RFC 7515) attestation bound to a requester nonce, with an expiry, whose payload carries the predicate parameters and the answer; plus an operator-published threshold menu (off-menu refused, never rounded). Signing: JWS, as the response-side counterpart of ICM's request-side DPoP claims (camara:bh / camara:qh).

Two scoping questions before we file, so we file it right:

• Route: the Scope Enhancement template is written for an existing API. For a catalog-wide response-envelope change, should we (a) file the Scope Enhancement here in APIBacklog naming Commonalities as the target, or (b) open an enhancement issue directly in the Commonalities repository?
• Aggregator item: we also have an optional item — end-to-end encryption through an aggregator so the hub meters and bills without reading identifiers or answers. Should that ride in the same enhancement, or be kept separate?

We will upload the OpenAPI sketch and the revised proposal document on issue #330 as supporting material, and would welcome a slot at the next APIBacklog WG session (10 or 24 September, whichever the chairs prefer) with a short deck covering the problem, the revised use cases, the signing choice, and the Scope Enhancement path.

[rartych]

Route: the Scope Enhancement template is written for an existing API. For a catalog-wide response-envelope change, should we (a) file the Scope Enhancement here in APIBacklog naming Commonalities as the target, or (b) open an enhancement issue directly in the Commonalities repository?

@hamr0 Feel free to open issue in https://github.com/camaraproject/Commonalities to propose signing mechanism - if it can be applied in many CAMARA APIs. Commonalites should define common guidelines in CAMARA API Design Guide.

[albertoramosmonagas]

Thank you for the update, accepted on all three points.

On the two questions:

1. Route — as @rartych confirms, open directly in Commonalities. File there first; the APIBacklog WG session can then reference the Commonalities issue rather than presenting a proposal that hasn't landed anywhere yet. That makes the September session more concrete.

2. Aggregator item — keep it separate. The signing envelope is already a meaningful scope addition; mixing in aggregator privacy mixes two distinct problems. File it as a follow-on once the baseline is accepted.

Suggested next steps:

1. Open the Scope Enhancement issue in camaraproject/Commonalities (JWS envelope + threshold menu, SimSwap /check as first adoption example).
2. Upload the OpenAPI sketch and revised proposal document on issue [API Proposal] CarrierAttestation #330 as supporting material.
3. Once the Commonalities issue is discussed, request a slot at the next APIBacklog WG session — presenting with an active Commonalities issue will make the discussion more grounded.
4. File the aggregator encryption item as a separate follow-on issue in Commonalities, referencing the signing-envelope one.

Are you agree with this @hamr0?

[hamr0]

Agreed on both points, and on all four next steps. Thank you both — the
route is now unambiguous.

Confirming the sequence we will follow:

1. Commonalities issue first. We will open the Scope Enhancement issue in camaraproject/Commonalities using that repo's Enhancement template. Scope is the response envelope only: a JWS (RFC 7515) attestation bound to a requester nonce, with an expiry, whose payload carries the predicate parameters and the answer; plus an operator-published threshold menu, where an off-menu threshold is refused and never silently rounded. First adoption example is SimSwap /check. Positioned as the response-side counterpart to ICM's request-side DPoP claims (camara:bh / camara:qh), so it can be written up in the CAMARA API Design Guide once agreed.

2. Supporting material on [API Proposal] CarrierAttestation #330. We will upload the OpenAPI sketch and the revised proposal document there, and link them from the Commonalities issue rather than duplicating the text.

3. WG slot after discussion, not before. We will request a slot once the Commonalities issue has had discussion, so the session references a live issue. Understood that this likely moves us past the 10 September session.

4. Aggregator item kept separate. The end-to-end encryption item (hub meters and bills without reading identifiers or answers) will be a distinct follow-on issue in Commonalities, filed only once the signing envelope baseline is accepted, and referencing it. Use case 2 (AI-agent holder presentment / trust directory) stays withdrawn from CAMARA, as stated above; it continues only on the IETF track.

We will post the Commonalities issue link back here once it is open.

_{Edited to repair three lines truncated by a paste error in the original post. No change of substance.}

[hamr0]

Step 1 is done. The Scope Enhancement issue is open in Commonalities:

camaraproject/Commonalities#705 — [Enhancement] Attested responses for CAMARA APIs — signed, nonce-bound, expiring answers; floor menu; range on open responses

It is scoped to the response envelope only, as agreed: a JWS (RFC 7515) attestation bound to a requester nonce with an expiry, verifiable offline via per-operator JWKS; the operator-published threshold menu, where an off-menu threshold is refused and never silently rounded; and a range rather than a point value on open-value predicates. SimSwap /check is the first adoption example. It is positioned as the response-side counterpart to the CAMARA Security and Interoperability Profile's request-side DPoP proof claims (camara:bh / camara:qh).

The aggregator end-to-end encryption item is held out, as agreed, and is stated in the issue as a deliberate omission rather than left silent. It will follow as a separate companion enhancement once this baseline is discussed.

Supporting material (revised proposal document and the OpenAPI sketch) will go on #330 next, linked from #705 rather than duplicated.

@albertoramosmonagas @rartych — thank you both for the routing guidance.

[albertoramosmonagas]

Hi @hamr0

Three points from today's Technical Steering Committee TSC discussion:

1. GSMA OPG e2e encryption context. There is parallel discussion in GSMA OPG on end-to-end encryption of responses. CarrierAttestation addresses signing, not encryption, but the two may need to coexist (e.g., signed, then encrypted through an aggregator). Is there a coordination path with OPG on response-layer mechanisms?
2. Impact on aggregators. The operator-published threshold menu and nonce binding change the aggregator's role — they meter and bill without reading the predicate or answer. Has the design been validated with aggregator operators? Will this require aggregator contract or capability changes?
3. Path to Security profile. This may eventually belong in CAMARA's Security and Interoperability Profile (potentially under ICM scope) rather than remaining a Commonalities pattern. Should the Scope Enhancement anticipate that trajectory, or is Commonalities the terminal home?

[hamr0]

Thank you for relaying the TSC's points.

1. GSMA OPG e2e encryption. They coexist, and the composition order matters: sign first, then encrypt to the requester. If the response were encrypted first and the signature applied over the ciphertext, the requester would end up verifying whoever did the encrypting, not the operator that made the assertion. Sign-then-encrypt keeps the operator's attestation verifiable end to end while the encryption layer hides it from any intermediary. Encryption itself stays out of this enhancement — that is already stated in [Enhancement] Attested responses for CAMARA APIs — signed, nonce-bound, expiring answers; floor menu; range on open responses Commonalities#705 as a deliberate omission, not left silent, and will follow as a separate companion enhancement (the "blind hub": end-to-end encryption of request and response through an aggregator, so the hub meters and bills without reading identifiers or answers). On coordination: I am an independent contributor with no member company, so I have no OPG seat and cannot carry this into OPG myself. I would welcome the TSC, or any member company, relaying it there. The filing does not conflict with an OPG response-encryption mechanism: signing is a separate layer, composing under the order above.

2. Aggregators. One correction first: what is filed signs the response; it does not encrypt it. An aggregator in the path can still read the identifier and the answer. "Meters and bills without reading the predicate or answer" describes the blind hub, which is held for the companion enhancement in point 1, not the current filing — this limit is stated on purpose in the proposal, not an oversight.

• Validated with aggregator operators: no. No aggregator operator has reviewed the design. Input from one would be welcome — that's a real gap the TSC could help close.
• Aggregator contract or interface change: no. No new endpoint, no new contract clause. The delta is additive — one request field (nonce) and one response field (attestation).
• Capability change: yes, one. Cache-substitution stops working. Today an aggregator that sees a query can read the answer and serve a later identical query from cache. With a requester-bound nonce and an expiry, a cached answer carries the wrong nonce and a dead exp, so it can't be substituted for a fresh query. That protects the operator's per-query billing against resale of a stale answer.

3. Commonalities vs. the Security and Interoperability Profile. Commonalities is the home now; I'd rather name a boundary condition than pre-commit a migration. Commonalities covers artifacts common to all APIs — data types, error formats, headers, the CloudEvents envelope — the request/response layer. The Security and Interoperability Profile (ICM, r4.2) restricts options within OIDC/CIBA — the token acquisition and presentation layer. The attestation is a response body field, carried in neither a token nor a DPoP proof, so structurally it sits in Commonalities. The boundary condition: the profile already does the mirror-image job request-side, with the camara:qh/camara:bh DPoP claims this filing cites as its counterpart. If the attestation's algorithm set, JWKS discovery, or replay window ever need normative pinning across providers, that part is profile work. The schema and pattern stay in Commonalities.