API-proposal-Network‑Authenticated-Assembly

[abd-abhisek]

#300

What type of PR is this?

Add one of the following kinds:

• enhancement/feature
• documentation

What this PR does / why we need it:

This PR introduces a new API proposal https://github.com/camaraproject/APIBacklog/issues/300

Which issue(s) this PR fixes:

https://github.com/camaraproject/APIBacklog/issues/300

Fixes #

Special notes for reviewers:

This PR provides the initial proposal for discussion in the API Backlog Working Group.
Feedback from the community is welcome regarding scope, alignment with existing CAMARA APIs, and potential collaboration

Changelog input

 release-note

Additional documentation

This section can be blank.

docs

[albertoramosmonagas]

Can you add this diagram to the actual PR?

[abd-abhisek]

I don’t know why can’t I upload any diagram/ document today. May be a security update from my organization. I have the deck ready for tomorrow discussion, unfortunately figuring out how do I upload /push and generate PR.

-- Regards Abhisek From: Alberto Ramos Monagas ***@***.***> Sent: Wednesday, March 11, 2026 4:55 PM To: camaraproject/APIBacklog ***@***.***> Cc: Abhisek Das ***@***.***>; Author ***@***.***> Subject: Re: [camaraproject/APIBacklog] API-proposal-Network‑Authenticated-Assembly (PR #305) [**EXTERNAL EMAIL**] Please verify sender address and exercise caution before clicking on any link. @albertoramosmonagas commented on this pull request.

________________________________ In documentation/API proposals/API-proposal-Network‑Authenticated-Assembly.md<#305 (comment)>:

+

+### Technical viability +Identify the underlying network/cloud capabilities which are needed for the support of this API or API family, relating these capabilities to standards maturity. +- Relies on **operator network-level device location capabilities** (e.g., 3GPP NEF/SCEF location services, Rel-15+). +- k-of-n threshold evaluation and group verdict aggregation are performed server-side by the NAA Group Evaluator component. +- Subscription/event model aligns with existing CAMARA CloudEvent patterns (same lifecycle as Geofencing Subscriptions). +- Attestation token provides a tamper-evident, privacy-preserving proof of co-presence for downstream workflow consumption. +- **Scope clarification:** cluster members are restricted to operator-addressable (SIM/eSIM/line-based) devices to ensure interoperability; non-SIM beacons/tags are out of scope. + +### Commercial viability +- No proprietary components required beyond standard network APIs already consumed by CAMARA Device Location +- Open-source reference: CAMARA DeviceLocation API implementation available in the CAMARA GitHub organization + +### YAML code available? +NO +Sequence diagram is available in deck Can you add this diagram to the actual PR? — Reply to this email directly, view it on GitHub<#305 (review)>, or unsubscribe<https://github.com/notifications/unsubscribe-auth/BBVOLGDTXIRTICXEM5YCTML4QFEIVAVCNFSM6AAAAACWOE35ZCVHI2DSMVQWIX3LMV43YUDVNRWFEZLROVSXG5CSMV3GSZLXHMZTSMRYHEYDENJWGA>. You are receiving this because you authored the thread.Message ID: ***@***.******@***.***>>

[albertoramosmonagas]

Hi @abd-abhisek, thanks for the PR. When you have the diagram and the PowerPoint presentation, can you attach them to this PR? Here are some points we can discuss in the backlog session:

1. Overlap: batch + k-of-n is not a new capability
   The underlying signal is still “presence in an area within a recent time window”. The proposed delta is mainly batching plus server-side aggregation into a group verdict. Please justify why this must be a new API family instead of a DeviceLocation scope enhancement (group co-presence) reusing existing area/time/error semantics.

2. Weak differentiation vs Location Verification
   “Location Verification requires exact lat/long” is not a strong differentiator: both approaches rely on a zone definition and return a verification outcome. Please restate the differentiation in normative terms: what cannot be achieved by Location Verification per device plus client-side aggregation, and why this must be standardized server-side for interoperability.

3. Consent/privacy is underspecified (multi-device inference)
   Group co-presence enables relationship inference (“who was with whom, where, when”). Please specify the authorization/consent model: enterprise-controlled fleet only (single tenant) vs multi-user clusters (user consent / 3-legged), and the data-minimization safeguards.

4. Subscriptions claim is too vague
   If “continuous checks” remain in scope, “aligns with CloudEvents” is not enough. Please specify the subscription resource model (endpoints, event types/payload, callback behavior, expiry/cancellation, quotas and lifecycle states).

[abd-abhisek]

Hi @abd-abhisek, thanks for the PR. When you have the diagram and the PowerPoint presentation, can you attach them to this PR? Here are some points we can discuss in the backlog session:

1. Overlap: batch + k-of-n is not a new capability
   The underlying signal is still “presence in an area within a recent time window”. The proposed delta is mainly batching plus server-side aggregation into a group verdict. Please justify why this must be a new API family instead of a DeviceLocation scope enhancement (group co-presence) reusing existing area/time/error semantics.
2. Weak differentiation vs Location Verification
   “Location Verification requires exact lat/long” is not a strong differentiator: both approaches rely on a zone definition and return a verification outcome. Please restate the differentiation in normative terms: what cannot be achieved by Location Verification per device plus client-side aggregation, and why this must be standardized server-side for interoperability.
3. Consent/privacy is underspecified (multi-device inference)
   Group co-presence enables relationship inference (“who was with whom, where, when”). Please specify the authorization/consent model: enterprise-controlled fleet only (single tenant) vs multi-user clusters (user consent / 3-legged), and the data-minimization safeguards.
4. Subscriptions claim is too vague
   If “continuous checks” remain in scope, “aligns with CloudEvents” is not enough. Please specify the subscription resource model (endpoints, event types/payload, callback behavior, expiry/cancellation, quotas and lifecycle states).

My challenge is I am unable to attach Deck, due to change in security policy possibly at my end. I really appreciate your review comments.
Let me try out add slides for each of the questions. I believe we have taken these into account, however keen to understand your and community perspective and refine as needed.
Thanks again

[abd-abhisek]

Hi @abd-abhisek, thanks for the PR. When you have the diagram and the PowerPoint presentation, can you attach them to this PR? Here are some points we can discuss in the backlog session:

1. Overlap: batch + k-of-n is not a new capability
   The underlying signal is still “presence in an area within a recent time window”. The proposed delta is mainly batching plus server-side aggregation into a group verdict. Please justify why this must be a new API family instead of a DeviceLocation scope enhancement (group co-presence) reusing existing area/time/error semantics.
2. Weak differentiation vs Location Verification
   “Location Verification requires exact lat/long” is not a strong differentiator: both approaches rely on a zone definition and return a verification outcome. Please restate the differentiation in normative terms: what cannot be achieved by Location Verification per device plus client-side aggregation, and why this must be standardized server-side for interoperability.
3. Consent/privacy is underspecified (multi-device inference)
   Group co-presence enables relationship inference (“who was with whom, where, when”). Please specify the authorization/consent model: enterprise-controlled fleet only (single tenant) vs multi-user clusters (user consent / 3-legged), and the data-minimization safeguards.
4. Subscriptions claim is too vague
   If “continuous checks” remain in scope, “aligns with CloudEvents” is not enough. Please specify the subscription resource model (endpoints, event types/payload, callback behavior, expiry/cancellation, quotas and lifecycle states).

My challenge is I am unable to attach Deck, due to change in security policy possibly at my end. I really appreciate your review comments. Let me try out add slides for each of the questions. I believe we have taken these into account, however keen to understand your and community perspective and refine as needed. Thanks again

@albertoramosmonagas I was able to upload the presentation, would be great if you and other colleagues can take a look before our next discussion. @bishnu-infy @hemantagogoi-infy @vijaymurthyn FYI Please

[albertoramosmonagas]

Hi @abd-abhisek ,

Thanks for uploading the updated deck — good progress, especially on interoperability (SIM/eSIM-only clusters, tags/beacons removed). Key backlog points still need to be closed with concrete, testable semantics:

1. Scope/overlap: the core still looks like “presence in an area within a recent time window”; the delta reads mainly batch + k-of-n aggregation. Please justify why this must be a new API family vs a DeviceLocation scope enhancement.

2. Differentiation vs Location Verification: “LV requires exact lat/long” is not a strong differentiator. Please state the delta in normative terms: what cannot be achieved via LV per device + client-side aggregation, and why server-side standardization is required for interoperability.

3. Consent/privacy: the two-mode framing (enterprise fleet vs multi-user) is a good step, but please define the portable auth/consent rules (especially for multi-user clusters) and the privacy/data-minimization safeguards.

4. Subscriptions: if “continuous checks” remain in scope, “aligned with CloudEvents” is not enough. Please specify the subscription model concretely (endpoints, event types/payload, callback/retries, expiry/cancellation, quotas/lifecycle, errors). Also, consider whether subscriptions can be deferred until on-demand semantics are validated.

Additionally, please clarify:

• Zone input: Area vs operator zoneId/discovery.
• Group verdict semantics: definition of “atomic” and rules for co_present/partial/not_co_present (time tolerance/maxAge, partial failures, device status handling).
• Attestation token: minimal format/claims, signature verification/key discovery, anti-replay.

[abd-abhisek]

Thanks @alberto Ramos ***@***.***> , appreciate the feedback, as a result we could refine the proposal as well. Kindly review this # Point Response 1 Why a new API family, not just an enhancement to DeviceLocation? DeviceLocation checks one device at a time. NAA answers a different question entirely: "Are these devices together?" — not "Where is this device?". The group verdict is produced atomically across all N devices at once. Calling DeviceLocation N times breaks that atomicity(indivisible/ granular most monolithic operation) and cannot produce a single signed attestation token. The distinction is architectural, not a feature flag. Promoting it as a DeviceLocation enhancement would also force callers to aggregate individual locations — increasing privacy exposure and destroying the attestation model 2 What exactly can't be done with Location Verification? Location Verification returns a per-device boolean. NAA returns a relational group verdict with a k-of-n threshold enforced server-side. Three things cannot be replicated client-side: (a) the aggregation logic must be identical across operators — standardization is required; (b) the attestation token must be verifiable by a downstream system without re-querying individual devices; (c) the partial state (some but not enough devices present) has no equivalent in Location Verification semantics 3 How does consent and privacy work? Two modes: (a) Enterprise fleet — all devices are operator-registered assets under a single enterprise tenant; no per-user consent needed beyond the enterprise subscription agreement. (b) Multi-user cluster — each device owner must grant explicit OAuth scope consent; NAA rejects the request if any consent is missing. In both cases, raw device locations never leave the operator — only the group verdict and attestation token are returned. No individual coordinates or identity linkage is ever exposed via the API. 4 What does the subscription model look like? The model is structurally identical to the Geofencing Subscriptions pattern. POST /assembly-subscriptions creates a subscription; events: assembly.co_present, assembly.partial, assembly.not_co_present; payload is a CloudEvent envelope with verdict, timestamp, and attestation token; delivery via HTTPS webhook with retries per CAMARA notification guidelines; expiry via maxDuration field; cancellation via DELETE /assembly-subscriptions/{id}. Detailed spec to be finalized during spec development. Clarifications Topic Response Zone input Callers specify the zone as part of the POST /verify request. Cluster members are identified by standard CAMARA device identifiers (phoneNumber, networkAccessIdentifier, ipv4Address/ipv6Address) — no operator-specific zone ID required Group verdict semantics co_present — k-of-n minimum devices confirmed in zone within time window. partial — at least one but fewer than k confirmed. not_co_present — minimum not met. Unreachable or non-consenting devices count as absent; their errors are reported alongside the verdict. partial is a first-class outcome, not an error state. Attestation token A signed token returned with every verdict — acts as a tamper-proof receipt. Downstream workflows can act on trusted presence without re-querying the API or seeing any device location. No individual device positions or identities are included in the token.

…

-- Regards Abhisek From: Alberto Ramos Monagas ***@***.***> Sent: Monday, April 6, 2026 3:28 PM To: camaraproject/APIBacklog ***@***.***> Cc: Abhisek Das ***@***.***>; Mention ***@***.***> Subject: Re: [camaraproject/APIBacklog] API-proposal-Network‑Authenticated-Assembly (PR #305) [**EXTERNAL EMAIL**] Please verify sender address and exercise caution before clicking on any link. [https://avatars.githubusercontent.com/u/194822567?s=20&v=4]albertoramosmonagas left a comment (camaraproject/APIBacklog#305)<#305 (comment)> Hi @abd-abhisek<https://github.com/abd-abhisek> , Thanks for uploading the updated deck — good progress, especially on interoperability (SIM/eSIM-only clusters, tags/beacons removed). Key backlog points still need to be closed with concrete, testable semantics: 1. Scope/overlap: the core still looks like “presence in an area within a recent time window”; the delta reads mainly batch + k-of-n aggregation. Please justify why this must be a new API family vs a DeviceLocation scope enhancement. 2. Differentiation vs Location Verification: “LV requires exact lat/long” is not a strong differentiator. Please state the delta in normative terms: what cannot be achieved via LV per device + client-side aggregation, and why server-side standardization is required for interoperability. 3. Consent/privacy: the two-mode framing (enterprise fleet vs multi-user) is a good step, but please define the portable auth/consent rules (especially for multi-user clusters) and the privacy/data-minimization safeguards. 4. Subscriptions: if “continuous checks” remain in scope, “aligned with CloudEvents” is not enough. Please specify the subscription model concretely (endpoints, event types/payload, callback/retries, expiry/cancellation, quotas/lifecycle, errors). Also, consider whether subscriptions can be deferred until on-demand semantics are validated. Additionally, please clarify: * Zone input: Area vs operator zoneId/discovery. * Group verdict semantics: definition of “atomic” and rules for co_present/partial/not_co_present (time tolerance/maxAge, partial failures, device status handling). * Attestation token: minimal format/claims, signature verification/key discovery, anti-replay. — Reply to this email directly, view it on GitHub<#305 (comment)>, or unsubscribe<https://github.com/notifications/unsubscribe-auth/BBVOLGFPNLPHNCXNRPBJT6T4UN5RFAVCNFSM6AAAAACWOE35ZCVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHM2DCOJRGUYTQMRRGY>. You are receiving this because you were mentioned.Message ID: ***@***.******@***.***>>

[albertoramosmonagas]

Hi @abd-abhisek ,

To make sure we’re all aligned before the next discussion, I have a few clarifying questions (mainly to turn the current statements into testable, portable semantics):

1. LV comparison: DeviceLocation LV also has PARTIAL/UNKNOWN (and match rate). When you say NAA adds “partial” with no LV equivalent, what exactly is the normative gap: k-of-n at group level, “atomic” timing, the attestation token, or something else?
2. Zone input: the deck says “no coordinates / no zone exposed”, but you also say callers specify the zone in POST /verify (no operator zoneId). Should we assume the caller provides a Commonalities Area object (which implies area coordinates), or some other zone reference? If it’s Area, are you ok to reword the deck to avoid confusion?
3. “Atomic” verdict: what is the intended normative definition (single evaluation timestamp vs time window with maxAge/timeTolerance per device)? How should unreachable/transient failures be treated (absent vs unknown) and reported?
4. Multi-user consent: how do you plan to collect/verify consent for multiple device owners in an interoperable way (given typical OAuth tokens are single-subject)? Would you consider scoping v0.x to enterprise fleet first and add multi-user later?
5. Subscriptions: do you expect the subscription resource (endpoints, lifecycle, payload, retries, expiry/cancel, errors) to follow the CAMARA event subscription template one-to-one, or any deviations?

Happy to review any updated text/deck changes or an early draft OAS snippet if you have one.

[abd-abhisek]

Hello @alberto Ramos ***@***.***> Thanks for time & review comments Q1. LV comparison: DeviceLocation LV also has PARTIAL/UNKNOWN (and match rate). When you say NAA adds "partial" with no LV equivalent, what exactly is the normative gap: k-of-n at group level, "atomic" timing, the attestation token, or something else? You're right that LV already returns PARTIAL and UNKNOWN for a single device. NAA's partial verdict means something fundamentally different — it is not about confidence in one device's position, it is about how many devices out of a group met the zone condition. So the core costruct is always different. Example: a cluster has 4 phones, threshold is 3. If 3 are in the zone and 1 is not, NAA returns partial (3-of-4 present, threshold met) or not_co_present (if threshold required all 4). LV has no concept of "3 out of 4 devices" — it only scpopes about one device. The normative gap is primarily k-of-n group evaluation: the operator evaluates the entire cluster server-side in one call and returns a single group-level verdict with a count. Secondary gaps are atomic timing (all devices evaluated within one bounded window, not N separate calls at different moments) and attestation token (a signed proof of the group result that downstream systems can trust without re-checking). None of these exist in LV — they are new semantics that cannot be replicated by calling LV per-device and aggregating client-side in a standardised, interoperable way.

…

________________________________ Q2. Zone input: the deck says "no coordinates / no zone exposed", but you also say callers specify the zone in POST /verify (no operator zoneId). Should we assume the caller provides a Commonalities Area object (which implies area coordinates), or some other zone reference? If it's Area, are you ok to reword the deck to avoid confusion? Yes, the caller provides a standard Commonalities Area object (circle or polygon with coordinates) in the request body. The deck phrase "no coordinates exposed" was meant to describe the response side — NAA never reveals any device's resolved location back to the caller. We acknowledge this wording caused confusion and will reword the deck to: "Zone is supplied by the caller as a standard Area object; no device coordinates are exposed in the response."

________________________________ Q3. "Atomic" verdict: what is the intended normative definition (single evaluation timestamp vs time window with maxAge/timeTolerance per device)? How should unreachable/transient failures be treated (absent vs unknown) and reported? "Atomic" means: all devices in the cluster are evaluated within a single bounded time window, defined by the caller's maxAge parameter. It is a time window, not a single-instant timestamp. Each device's last-known position must fall within maxAge of the evaluation moment. Failure handling: * Unreachable (device off, no coverage): reported per-device as UNREACHABLE, counts as not present toward k-of-n. * Transient error (temporary network issue): reported per-device as UNKNOWN, also counts as not present. * If unreachable + unknown devices push the present count below k, verdict becomes partial or not_co_present.

________________________________ Q4. Multi-user consent: how do you plan to collect/verify consent for multiple device owners in an interoperable way (given typical OAuth tokens are single-subject)? Would you consider scoping v0.x to enterprise fleet first and add multi-user later? Yes — v0.x will scope to enterprise/fleet only. All devices belong to one organisation, authorised under a single client-credentials OAuth token. No multi-user consent is needed. For later versions, we will collaborate with the Commonalities WG to define a multi-user consent model (e.g., per-user pre-authorisation or consent registry)

________________________________ Q5. Subscriptions: do you expect the subscription resource (endpoints, lifecycle, payload, retries, expiry/cancel, errors) to follow the CAMARA event subscription template one-to-one, or any deviations? One-to-one. Same create/query/delete lifecycle, CloudEvents payload (org.camaraproject.device-assembly.v0.status-changed), same retry and expiry rules. We may propose an optional PATCH for threshold/expiry updates, but will drop it if the WG prefers not to. We also agree subscriptions can be deferred to a later release — we'll work on on-demand POST /verify first.

-- Regards Abhisek From: Alberto Ramos Monagas ***@***.***> Sent: Wednesday, April 8, 2026 3:08 PM To: camaraproject/APIBacklog ***@***.***> Cc: Abhisek Das ***@***.***>; Mention ***@***.***> Subject: Re: [camaraproject/APIBacklog] API-proposal-Network‑Authenticated-Assembly (PR #305) [**EXTERNAL EMAIL**] Please verify sender address and exercise caution before clicking on any link. [https://avatars.githubusercontent.com/u/194822567?s=20&v=4]albertoramosmonagas left a comment (camaraproject/APIBacklog#305)<#305 (comment)> Hi @abd-abhisek<https://github.com/abd-abhisek> , To make sure we’re all aligned before the next discussion, I have a few clarifying questions (mainly to turn the current statements into testable, portable semantics): 1. LV comparison: DeviceLocation LV also has PARTIAL/UNKNOWN (and match rate). When you say NAA adds “partial” with no LV equivalent, what exactly is the normative gap: k-of-n at group level, “atomic” timing, the attestation token, or something else? 2. Zone input: the deck says “no coordinates / no zone exposed”, but you also say callers specify the zone in POST /verify (no operator zoneId). Should we assume the caller provides a Commonalities Area object (which implies area coordinates), or some other zone reference? If it’s Area, are you ok to reword the deck to avoid confusion? 3. “Atomic” verdict: what is the intended normative definition (single evaluation timestamp vs time window with maxAge/timeTolerance per device)? How should unreachable/transient failures be treated (absent vs unknown) and reported? 4. Multi-user consent: how do you plan to collect/verify consent for multiple device owners in an interoperable way (given typical OAuth tokens are single-subject)? Would you consider scoping v0.x to enterprise fleet first and add multi-user later? 5. Subscriptions: do you expect the subscription resource (endpoints, lifecycle, payload, retries, expiry/cancel, errors) to follow the CAMARA event subscription template one-to-one, or any deviations? Happy to review any updated text/deck changes or an early draft OAS snippet if you have one. — Reply to this email directly, view it on GitHub<#305 (comment)>, or unsubscribe<https://github.com/notifications/unsubscribe-auth/BBVOLGB5APNRPJEVFED457L4UYMWZAVCNFSM6AAAAACWOE35ZCVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHM2DEMBVGI4DSMBTGM>. You are receiving this because you were mentioned.Message ID: ***@***.******@***.***>>

[albertoramosmonagas]

Hi @abd-abhisek,

I agree “partial” in NAA is a group completeness concept rather than LV’s single-device confidence. One quick clarification to avoid semantic ambiguity: in your example (N=4, k=3, m=3 present) you mention NAA would return “partial” even though the threshold is met. Does that mean:

• co_present = all N present, and partial = threshold met but not all present?
  or
• co_present = threshold met (m ≥ k), and partial = threshold not met but some present (0 < m < k)?

Could you please confirm the intended truth table (verdict vs m/N/k) and update the deck/PR text accordingly? Also, will the response include at least requiredCount/totalCount/presentCount so relying parties can interpret “partial” consistently across operators?

[abd-abhisek]

Hello @alberto Ramos ***@***.***> Verdict truth table (I feel this is more logical) `co_present` = All present (m = N) `partial` = Threshold met, not all (k ≤ m < N) `not_co_present` = Below threshold (m < k) So in the example (N=4, k=3, m=3): verdict is `partial`. However, this is the concept. We can review this and update as necessary while developing the Swagger spec. Response fields: Yes, the response will include `totalCount` (N), `requiredCount` (k), and `presentCount` (m) so relying parties can interpret the verdict consistently across operators. We will update the deck and PR text with this truth table. Only challenge is my organization changed firewall policies and unable to push documents to Git. But will figureout a way and update this.

…

-- Regards Abhisek From: Alberto Ramos Monagas ***@***.***> Sent: Wednesday, April 8, 2026 7:03 PM To: camaraproject/APIBacklog ***@***.***> Cc: Abhisek Das ***@***.***>; Mention ***@***.***> Subject: Re: [camaraproject/APIBacklog] API-proposal-Network‑Authenticated-Assembly (PR #305) [**EXTERNAL EMAIL**] Please verify sender address and exercise caution before clicking on any link. [https://avatars.githubusercontent.com/u/194822567?s=20&v=4]albertoramosmonagas left a comment (camaraproject/APIBacklog#305)<#305 (comment)> Hi @abd-abhisek<https://github.com/abd-abhisek>, I agree “partial” in NAA is a group completeness concept rather than LV’s single-device confidence. One quick clarification to avoid semantic ambiguity: in your example (N=4, k=3, m=3 present) you mention NAA would return “partial” even though the threshold is met. Does that mean: * co_present = all N present, and partial = threshold met but not all present? or * co_present = threshold met (m ≥ k), and partial = threshold not met but some present (0 < m < k)? Could you please confirm the intended truth table (verdict vs m/N/k) and update the deck/PR text accordingly? Also, will the response include at least requiredCount/totalCount/presentCount so relying parties can interpret “partial” consistently across operators? — Reply to this email directly, view it on GitHub<#305 (comment)>, or unsubscribe<https://github.com/notifications/unsubscribe-auth/BBVOLGHMB6IXTZCF5TG7OST4UZIIXAVCNFSM6AAAAACWOE35ZCVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHM2DEMBWGYYDSMBZGE>. You are receiving this because you were mentioned.Message ID: ***@***.******@***.***>>