diff --git a/apps/site/.gitignore b/apps/site/.gitignore index 8282e9e6e..527dc693f 100644 --- a/apps/site/.gitignore +++ b/apps/site/.gitignore @@ -20,6 +20,8 @@ node_modules/ /content/docs/spec-collection-profile.mdx /content/docs/spec-connector-ecosystem.mdx /content/docs/spec-core.mdx +/content/docs/spec-access-extension.mdx +/content/docs/spec-mcp-profile.mdx /content/docs/spec-data-query-api.mdx /content/docs/spec-discovery-and-trust.mdx /content/docs/governance.mdx diff --git a/apps/site/content/docs/meta.json b/apps/site/content/docs/meta.json index 911a8621e..97124f55e 100644 --- a/apps/site/content/docs/meta.json +++ b/apps/site/content/docs/meta.json @@ -4,6 +4,8 @@ "pages": [ "---Specification---", "spec-core", + "spec-access-extension", + "spec-mcp-profile", "spec-ext-lexical-search", "spec-ext-aggregation", "spec-semantic-retrieval-extension", diff --git a/apps/site/next.config.mjs b/apps/site/next.config.mjs index 8e5a2d248..ad8c69f55 100644 --- a/apps/site/next.config.mjs +++ b/apps/site/next.config.mjs @@ -144,6 +144,16 @@ const nextConfig = { permanent: true, source: "/spec-collection-profile", }, + { + destination: "/specification/spec-access-extension", + permanent: true, + source: "/spec-access-extension", + }, + { + destination: "/specification/spec-mcp-profile", + permanent: true, + source: "/spec-mcp-profile", + }, { destination: "/specification/spec-architecture", permanent: true, diff --git a/apps/site/scripts/sync-spec-docs.mjs b/apps/site/scripts/sync-spec-docs.mjs index 1b8010962..ae5f5ace5 100644 --- a/apps/site/scripts/sync-spec-docs.mjs +++ b/apps/site/scripts/sync-spec-docs.mjs @@ -41,12 +41,14 @@ const headerDir = path.join(siteDir, "spec-headers"); // Non-spec docs (reference-implementation*, open-questions, extension specs, // index, README) live only under content/docs and are NOT touched here. const SPECS = [ + "spec-access-extension", "spec-architecture", "spec-auth-design", "spec-change-tracking", "spec-collection-profile", "spec-connector-ecosystem", "spec-core", + "spec-mcp-profile", "spec-data-query-api", "spec-discovery-and-trust", ]; @@ -74,7 +76,12 @@ function toMdxSafe(body) { // as the start of a tag name; `)` cannot start a tag name, so the parse // fails. Backtick-quoting it (already how this table quotes every other // token) makes the comparison operator literal. - .replace("(exclusive, <), evaluated", "(exclusive, `<`), evaluated")); + .replace("(exclusive, <), evaluated", "(exclusive, `<`), evaluated") + // MDX does not accept HTML comments (`` next to a value; carry them into the + // site copy as MDX comments so they stay invisible there too. + .replace(//g, "{/* $1 */}")); } // Root header shape (uniform across all spec files): // line 1: `# ` diff --git a/apps/site/scripts/sync-spec-docs.mts b/apps/site/scripts/sync-spec-docs.mts index 579adacc7..02b630505 100644 --- a/apps/site/scripts/sync-spec-docs.mts +++ b/apps/site/scripts/sync-spec-docs.mts @@ -45,12 +45,14 @@ const headerDir = path.join(siteDir, "spec-headers"); // Non-spec docs (reference-implementation*, open-questions, extension specs, // index, README) live only under content/docs and are NOT touched here. const SPECS = [ + "spec-access-extension", "spec-architecture", "spec-auth-design", "spec-change-tracking", "spec-collection-profile", "spec-connector-ecosystem", "spec-core", + "spec-mcp-profile", "spec-data-query-api", "spec-discovery-and-trust", ]; @@ -81,6 +83,11 @@ function toMdxSafe(body) { // fails. Backtick-quoting it (already how this table quotes every other // token) makes the comparison operator literal. .replace("(exclusive, <), evaluated", "(exclusive, `<`), evaluated") + // MDX does not accept HTML comments (`<!--` fails as a tag name). The + // root specs use single-line editorial markers such as + // `<!-- OWNER DECISION OD-4 -->` next to a value; carry them into the + // site copy as MDX comments so they stay invisible there too. + .replace(/<!--[ \t]*(.*?)[ \t]*-->/g, "{/* $1 */}") ); } diff --git a/apps/site/spec-headers/spec-access-extension.header.md b/apps/site/spec-headers/spec-access-extension.header.md new file mode 100644 index 000000000..0324d92af --- /dev/null +++ b/apps/site/spec-headers/spec-access-extension.header.md @@ -0,0 +1,8 @@ +--- +title: Extended access profile +description: Optional owner-selected authorization, grant packages, and presentation reads. +--- + +<Callout type="warn"> +Draft. Implementation and interoperability remain to be tested. +</Callout> diff --git a/apps/site/spec-headers/spec-mcp-profile.header.md b/apps/site/spec-headers/spec-mcp-profile.header.md new file mode 100644 index 000000000..b01739514 --- /dev/null +++ b/apps/site/spec-headers/spec-mcp-profile.header.md @@ -0,0 +1,8 @@ +--- +title: MCP read profile +description: Draft binding of MCP tool access to PDPP grants. +--- + +<Callout type="warn"> +Draft. Not an adopted standard or implemented conformance claim. +</Callout> diff --git a/apps/site/src/app/(concept)/build/page.tsx b/apps/site/src/app/(concept)/build/page.tsx index f89ace207..f982941e1 100644 --- a/apps/site/src/app/(concept)/build/page.tsx +++ b/apps/site/src/app/(concept)/build/page.tsx @@ -97,7 +97,7 @@ const FAQS: readonly Faq[] = [ role: "Building an accessor", question: "Which purpose code do I put in my request?", answer: - "Every grant names a purpose from the registry. Most requests fit an existing code, and ai_training is the one that triggers a protocol-level consent step. If nothing fits you can propose one, and proposals are considered on a published cycle.", + "Every grant names a purpose from the registry. Most requests fit an existing code. If nothing fits you can propose one, and proposals are considered on a published cycle. Under the revised Core draft, a purpose never authorizes AI training: training is a separate processing permission that stays unavailable until the AI Training Profile is published and registered.", cta: "Purpose registry", href: "/specification#purpose-registry", }, diff --git a/apps/site/src/components/sections/reference-app.tsx b/apps/site/src/components/sections/reference-app.tsx index 460b3711e..b46d04622 100644 --- a/apps/site/src/components/sections/reference-app.tsx +++ b/apps/site/src/components/sections/reference-app.tsx @@ -1889,7 +1889,10 @@ Content-Type: application/json monogram instead of fetching arbitrary remote logos. </p> <p> - ai_training purpose code requires explicit affirmative consent — the sole protocol-level requirement. + The revised Core draft reserves AI training as a separate processing permission. Training remains + unavailable until the AI Training Profile is published and registered. The reference implementation + still uses the earlier purpose-code consent rule; that rule confers no training authority under the + revised draft. </p> </DetailPanel> } @@ -2222,8 +2225,11 @@ Introspection cache TTL ≤ 60 seconds RS sees revocation within max(token_exp, 60s)`} </pre> <p> - Revocation stops <em>future</em> access only. Records already delivered are governed by the grant's - retention policy and legal obligations. PDPP does not retroactively reach into client-side data stores. + Revocation ends <em>future</em> reads. On owner withdrawal, the owner chooses keep or delete for held + data. Keep permits only the grant's surviving use: ordinary grants allow use within purpose and + retention; processing-permission grants allow custody only, subject to the learned-parameter exception. + Delete is an erasure instruction the client must act on. Clients learn of it through the grant lifecycle + operation. </p> <p> Grant narrowing is not supported in v0.1. Scope reduction: revoke the existing grant, issue a new diff --git a/apps/site/src/lib/spec-nav-slugs.ts b/apps/site/src/lib/spec-nav-slugs.ts index 1c45fbf08..c96026c2e 100644 --- a/apps/site/src/lib/spec-nav-slugs.ts +++ b/apps/site/src/lib/spec-nav-slugs.ts @@ -34,6 +34,8 @@ export const PRIMARY_SLUGS = ["spec-core"] as const; export const GUIDANCE_SLUGS = [ "spec-discovery-and-trust", "spec-collection-profile", + "spec-access-extension", + "spec-mcp-profile", "spec-ext-lexical-search", "spec-ext-aggregation", "spec-semantic-retrieval-extension", @@ -54,12 +56,14 @@ export const GUIDANCE_SLUGS = [ // the self-host coverage table) reads it from here so the two lists cannot // silently diverge in three different places instead of one. export const GENERATED_MDX_SPEC_SLUGS = [ + "spec-access-extension", "spec-architecture", "spec-auth-design", "spec-change-tracking", "spec-collection-profile", "spec-connector-ecosystem", "spec-core", + "spec-mcp-profile", "spec-data-query-api", "spec-discovery-and-trust", ] as const; diff --git a/docs/reference/consultation-agenda.md b/docs/reference/consultation-agenda.md index 58915a9cc..35eaeb98a 100644 --- a/docs/reference/consultation-agenda.md +++ b/docs/reference/consultation-agenda.md @@ -255,6 +255,12 @@ policy and applicable legal obligations. The specification deliberately does not overload revocation responses or introspection state to imply downstream erasure, and no active erasure signal is defined in v0.1. +**Superseded.** The paragraph above records the position the consultation +opened on. A proposed held-data revision would replace it: every owner withdrawal carries a +keep or delete disposition, and clients learn of erasure instructions through +the grant lifecycle operation +([spec-core, held data](https://www.pdpp.dev/docs/spec-core#held-data)). + **What input helps.** Prior art on machine-to-machine deletion requests and their acknowledgment (including how legal-hold and retention obligations are represented). A view on whether erasure belongs in Core or in a companion diff --git a/scripts/spec-check.ts b/scripts/spec-check.ts index 9334836c5..ad23a224b 100644 --- a/scripts/spec-check.ts +++ b/scripts/spec-check.ts @@ -192,11 +192,17 @@ const ANCHOR_ID_PATTERN = /[ \t]+[[{]#[A-Za-z0-9_-]+[\]}]/g; // expected, allowlisted difference rather than reported drift. const BARE_LT_ESCAPE_PATTERN = /\(exclusive, `<`\), evaluated/g; +// sync-spec-docs.mjs's toMdxSafe also turns a root HTML comment such as +// `<!-- OWNER DECISION OD-4 -->` into an MDX comment `{/* OWNER DECISION OD-4 */}`, +// because MDX rejects `<!--`. Map the site form back to the root form. +const MDX_COMMENT_PATTERN = /\{\/\* (.*?) \*\/\}/g; + function normalizeBody(text: string): string { return text .replace(CRLF_PATTERN, "\n") .replace(ANCHOR_ID_PATTERN, "") .replace(BARE_LT_ESCAPE_PATTERN, "(exclusive, <), evaluated") + .replace(MDX_COMMENT_PATTERN, "<!-- $1 -->") .split("\n") .map((line) => line.trimEnd()) .join("\n") diff --git a/spec-access-extension.md b/spec-access-extension.md new file mode 100644 index 000000000..b6a81cdab --- /dev/null +++ b/spec-access-extension.md @@ -0,0 +1,178 @@ +# PDPP extended access profile + +Status: Draft extension profile; profile version 0.1.0 +Date: 2026-10-13 + +## 1. Scope and status + +This companion profile defines optional, transport-neutral extensions for PDPP authorization and disclosure: owner-selected authorization, grant packages, and bounded presentation reads. These features are independent; an implementation MAY support any subset. + +This profile does not broaden a Core grant, replace the Core resource-server interface, or define a new authorization framework. A claiming implementation MUST satisfy applicable Core conformance requirements. Core remains the authority for grant shape, result delivery, lifecycle, and enforcement. + +## 2. Requirements language + +The key words MUST, MUST NOT, REQUIRED, SHALL, SHALL NOT, SHOULD, SHOULD NOT, RECOMMENDED, MAY, and OPTIONAL are to be interpreted as described in RFC 2119 and RFC 8174 when, and only when, they appear in capitals. + +## 3. Profile claims and common boundary + +A conformance claim MUST identify the profile version, transport binding, protected-resource surface, and data surface covered, and MUST list each supported feature separately. Claiming one feature MUST NOT imply support for another, and no implementation is required to support all features. + +If an implementation claims a feature, its advertised support and actual behavior MUST satisfy every requirement for that feature. The transport binding MUST select and validate the intended protected-resource identifier for each request or package token. + +This profile does not redefine the Core client-visible authorization result. Clients and authorization servers MUST follow Core Section 7 for the complete `{ type, grant }` result, including refresh responses, and client inspection before disclosure. The authorization-details envelope remains the deployment's RFC 9396 binding. + +A separated resource server MUST resolve an access token through authenticated RFC 7662 introspection; a co-located deployment MAY use an authenticated local equivalent. The response MUST contain complete request context. Positive introspection caching MUST respect Core's maximum positive-cache lifetime. + +Malformed, incomplete, contradictory, or context-mismatched required introspection data MUST fail closed. Unknown extension members MUST NOT alone cause rejection or confer authority. The resource server MUST determine `pdpp_token_kind` from the authenticated result, never token syntax. + +In this profile, a client's pairwise identifiers are the identifiers that Core's [Pairwise identifiers](spec-core#pairwise-identifiers) rules give that client. They include a `subject.id` that the owner chose to disclose to that client under Core's owner-choice exception. + +## 4. Owner-selected authorization + +An authorization server MAY support owner-selected authorization with RFC 9396 type `https://pdpp.dev/owner-selection`. This OPTIONAL feature is not a replacement for Core type `https://pdpp.dev/data-access`. + +An AS supporting owner selection MUST advertise `https://pdpp.dev/owner-selection` in `authorization_details_types_supported`. A client MUST establish support before requesting it. + +The request MUST identify the requesting client through the selected authorization binding and MUST contain `purpose_code` and `access_mode`. It MAY contain `purpose_description`, `retention`, `processing_permissions`, and a non-empty `source_ids` array. `access_mode` MUST retain Core's `single_use` or `continuous` semantics. `processing_permissions` has Core's meaning and validation ([Processing permissions](spec-core#processing-permissions)). + +The AS MAY resolve purpose and retention from recipient-authorized standing terms, but MUST identify and version those terms in retained consent evidence. An owner-authored condition alone MUST NOT be treated as recipient acceptance. This profile creates no unreviewed terms field or unilateral recipient commitment. + +The AS MUST resolve owner selection under Core's [Authorization privacy boundary](spec-core#authorization-privacy). A source identifier in `source_ids` limits the requested selection; it does not establish that the owner has connected or may authorize that source. The AS MUST offer only sources with accepted declarations that are eligible for the authenticated owner. The AS MUST NOT accept or retrieve a new declaration authority because the request names a source. + +When `source_ids` is present, the AS MUST limit selection to those identifiers. When it is absent, the AS MAY offer any eligible accepted source. The AS MUST keep that offered inventory within the authenticated owner's review interaction. + +A source that cannot be offered MUST remain unapproved. The AS MUST NOT identify it to the client as unknown, unconnected, unaccepted, or ineligible. The AS MUST NOT reject an otherwise valid request before owner authentication because such a source is listed. + +Duplicate source identifiers or unknown request members MUST produce RFC 9396 `invalid_authorization_details`. An empty final selection MUST produce `access_denied`. The request does not require an initial stream selector; the owner's selection supplies that choice. + +An owner-selection detail carries one purpose. Every detail it resolves has that purpose. A client that needs several purposes MUST send one owner-selection detail per purpose, in one request or in separate requests. The owner approves or declines each resolved detail on its own, as Core Section 7 requires. + +Core's [processing-permission consent rules](spec-core#processing-permissions) apply inside owner selection. Every detail resolved from an owner-selection detail carries that detail's exact `processing_permissions` set. When the set is non-empty, the owner MUST select each source for it by a distinct affirmative action. The AS MUST NOT present any such source as selected by default. The owner MUST be able to approve every other detail in the transaction while declining any such source. The AS MUST NOT drop the set from a resolved detail or issue an ordinary grant in its place. + +Before token issuance, the AS MUST resolve each selected source to one ordinary Core data-access detail with the owner-selection detail's purpose and processing permissions, and then to one grant. The result MUST contain one complete `{ type, grant }` element per issued grant. Each grant MUST contain explicit streams, instance handles, fields, `required_fields`, resources, and time constraints required by Core and the retained declaration snapshot. Its `subject.id` and instance handles are the requesting client's pairwise identifiers ([Pairwise identifiers](spec-core#pairwise-identifiers)). For a stream with `resources`, the owner selects exactly one instance, as Core Section 7 requires. Each resolved field set includes the stream's schema-required fields; they are the per-stream consent floor that Core Section 6 defines. Owner narrowing MUST NOT remove them. + +If the transaction issues more than one grant, the AS MUST issue a package under Section 5. If the AS cannot issue a package, because it lacks package support or an element lacks `detail_id`, it MUST accept at most one requested `authorization_details` element in the entire request. It MUST issue at most one grant. It MUST reject a multi-element request with `invalid_authorization_details`. In the single-element case, the sole returned grant is that element's outcome. + +An AS that does not support this type MUST reject it as unsupported and MUST NOT silently process it as Core data access. Absence of `authorization_details` is not opt-in and MUST NOT enable this flow. Final owner review MUST identify the client, resolved data, purpose, processing permissions, access mode, retention, and recipient-authorized standing terms affecting the decision. It MUST also show what happens to held data after each resolved grant ends, as Core [Recipient commitments and approval](spec-core#recipient-commitments) requires. + +## 5. Grant packages + +A grant package is one access token, and at most one refresh-token family, that covers several ordinary Core grants. A package is a profile binding over those grants, not a Core grant or Core token kind. Each covered grant is a child. + +### 5.1 Children and detail correlation + +An AS MAY issue a package when a transaction requests more than one detail, or an owner-selection detail, and the client sent `detail_id` on every element. A resolved detail covers one subject, one source, and one purpose (Core Section 7). A requested Core `data-access` detail is one resolved detail. An owner-selection detail resolves to one detail per selected source (Section 4). + +The package MUST contain one complete Core grant per issued resolved detail. Several children MAY share a source, for example when their purposes differ. `grant_id` identifies a child. Subject, source, and purpose together are not a key. + +Each child MUST retain its `source.id`, declaration revision, resolved constraints, processing permissions, client and subject bindings, and lifecycle. The AS MUST NOT merge fields, instances, resources, or constraints across children. The AS MUST bind every child to the authenticated client and subject and MUST reject packages combining different clients or subjects. + +Every child is a Core grant for the same client, so it carries that client's pairwise identifiers ([Pairwise identifiers](spec-core#pairwise-identifiers)). Instance handles are scoped to issuer, subject, and client and are unique across sources, as Core requires. They are not scoped to a child: two children that cover the same instance list the same handle, and their records carry the same `instance_id`. The client MAY relate records across its own children by `instance_id` and `id`. This does not permit the resource server to compute a result across children (Section 5.3). Each child is subject to Core's `resources` rule: a child stream with `resources` lists exactly one handle. The AS MUST reject a detail that asks for `resources` in more than one instance with RFC 9396 `invalid_authorization_details`, and MUST NOT split it into several children. + +Correlation uses a `detail_id` member on each requested `authorization_details` element: a string, unique within the request, chosen by the client. In the OAuth binding, an AS signals package support by advertising `pdpp_package_disconnect_endpoint` (Section 5.6). A client MUST send `detail_id` only to an AS that advertises that endpoint. A client that can accept a package MUST then send `detail_id` on every element. The AS MUST reject an empty or duplicate `detail_id` with RFC 9396 `invalid_authorization_details`. It MUST NOT issue a package for a request in which an element lacks `detail_id`. + +The token response that first issues the package MUST contain `pdpp_detail_outcomes`: an array with one `{ detail_id, grant_ids }` entry per requested detail. `grant_ids` lists the `grant_id` of every child issued for that detail. An empty `grant_ids` means the detail was declined. For an owner-selection detail, the entry lists only the issued children. The AS MUST NOT reveal which sources the owner saw, declined, or could have selected. + +The AS MUST apply Core's [Authorization privacy boundary](spec-core#authorization-privacy) when resolving children. An empty `grant_ids` list MUST NOT distinguish owner refusal from owner-dependent ineligibility. The AS MUST NOT add per-source rejection reasons, candidate counts, or unapproved instance identifiers to `pdpp_detail_outcomes`. + +The owner approves or declines each resolved detail on its own. A package with exactly one issued child is still a package: the client selects that child as Section 5.3 requires. When no child is issued, the AS MUST refuse the authorization with `access_denied` and MUST NOT issue a token. + +### 5.2 Introspection and read deadlines + +An active package introspection response MUST report `pdpp_token_kind: "grant_package"`, the `authorization_details` of every child the token carries, and `pdpp_grant_read_active`. `pdpp_grant_read_active` maps the `grant_id` of every child of the package to a boolean that says whether the child currently authorizes reads. A child that the token no longer carries is reported `false`. The AS MUST compute each value from current lifecycle and report top-level `active: false` when the token is invalid or no child is active. An inactive response MAY omit the grant context. `pdpp_grant_read_active` and `pdpp_grant_read_until` describe read access only, not processing authority ([Read access and processing authority](spec-core#processing-authority)). Neither is a lifecycle answer or a [positive assessment](spec-core#reconciliation). A client learns whether it may keep and use a child's held data only from token responses and the Core [grant lifecycle operation](spec-core#grant-lifecycle). A package token authenticates lifecycle queries for each of its children. + +For each `single_use` child, an active response MUST also report the child's read deadline in `pdpp_grant_read_until`, which maps that child's `grant_id` to a Unix epoch time. The deadline is the expiry of the first package token that carried the child, which ends the child's Core read window. The AS MUST fix the deadline at that issuance and MUST NOT change it. A child is inactive after its deadline, even if its underlying grant has not expired. + +The resource server MUST NOT use a positive cache entry for a child after that child's read deadline. A signed blob URL for a `single_use` child MUST expire no later than the child's read deadline, and blob redemption MUST check the deadline again. + +Package introspection omits the singular Core client-context `grant_id`; this extension context MUST NOT be treated as an ordinary Core client context. + +An active package introspection response MUST also carry Core's RS-only `pdpp_instance_bindings` for every child the token carries. Each entry is `{ grant_id, source_id, stream, instance_id, rs_instance }`, one for each child, stream, and handle in that child's grant, where `grant_id` names the child. The Core consistency rule applies across the whole response: every entry for one `(source_id, instance_id)` MUST name the same `rs_instance`, and the resource server MUST reject a response with conflicting entries as `grant_invalid` before it serves data under any child. The resource server MUST resolve handles for a request only from the entries of the selected child. A request under a child that needs a handle with no entry for that child, or whose entry names no stored instance, fails with 403 `grant_invalid`, as Core Section 8 defines; the failure does not affect another child. The AS MUST NOT return `pdpp_instance_bindings` or `rs_instance` to a client. + +The package token MUST remain bound to the intended protected resource selected by the transport binding. Its token kind MUST NOT confer owner authority. A resource server with package endpoints MUST list `grant_package` in its `pdpp_token_kinds_supported` metadata; Core Section 8 lets a companion profile add a token kind. + +A Core-only endpoint implements Core and not this binding. It MUST reject a token with `pdpp_token_kind: "grant_package"`. A package endpoint implements this binding. In the HTTP binding, package endpoints reuse the Core Section 8 paths and response shapes. They add the child selector of Section 5.3 and answer each request as the Core endpoint would under the selected child's grant alone. A package endpoint also serves Core client tokens as Core defines. A resource server that implements the binding MUST identify its package endpoints in the protected-resource surface of its conformance claim (Section 3). + +### 5.3 Child selection + +Every disclosure made with a package token, other than child discovery (below), MUST name exactly one child by `grant_id`. This applies to list streams, stream metadata and schema reads, record lists, single-record reads, `changes_since` reads, blob fetches, presentation operations such as search (Section 6), and each sub-call of an operation that fans out across children. There is no implicit selection, even when the package has one child or one active child. + +Child discovery is exempt from the selector rule. A binding MAY define an operation that lists the children of the presented token. It returns only the approved grant metadata of those children and their current status. Any subject, grantor, or instance identifier it returns is the client's pairwise value from the child grant, and it lists only the instance handles that the child grant lists. It MUST NOT return records, derived facts, or inventory of sources, grants, or instances that the owner did not approve. + +For an operation that requires child selection, the resource server MUST reject a missing, malformed, repeated, or unknown selector before it processes the request. An unknown selector names a `grant_id` that is not a child of the package. The HTTP binding returns HTTP 400 `invalid_request` with `param` naming the selector. The resource server MUST NOT fall back to another child. + +The resource server MUST verify client, subject, intended-resource, and child bindings before it uses the selected child. It MUST reject incomplete status mappings and context mismatch, and MUST require both package and selected-child active status for disclosure. + +The resource server MUST apply the selected child's `required_fields` independently for each stream. The resource server MUST NOT substitute a required-field set from another child, including a child for the same source and stream. + +The resource server MUST authorize each disclosure under the selected child alone. It MUST NOT combine the constraints of several children to authorize a disclosure. It MUST NOT compute a result across children, such as a count, ranking, join, deduplication, or summary. An operation that spans children MUST make one sub-call per child, and each sub-call MUST name its own child. A binding MAY return the sub-call results in one envelope. Each entry is labeled with its child's `grant_id` and is either that child's independently authorized result or that child's error, including `package_child_inactive`. One entry's error does not change another entry. A sub-call that establishes its child's status without introspection MUST meet Core [Lifecycle durability](spec-core#lifecycle-durability). + +A read names an instance by Core's `instance_id`. The resource server computes the Core selector requirement from the selected child's grant alone: a single-record read or delete requires `instance_id` when that child's grant lists more than one handle for the stream, and every blob fetch requires `instance_id`. A handle that the selected child's grant does not list for the stream is not found, as Core Section 8 defines, even when another child of the package lists it. Every record, tombstone, and `fetch_url` served under a child carries the client's handle, and each `resource_ref` is resolved or redacted under the selected child's grant alone, as Core Section 4 defines. + +Cursors, `changes_since` tokens, signed blob URLs, and cache entries are bound to the selected child. The resource server MUST reject a cursor or `changes_since` token presented under another child with HTTP 400 `invalid_cursor`. A signed blob URL binds its child at issuance, and redemption MUST check that the child is still active. A cache of responses or derived data MUST include the child's `grant_id` in its key. It MUST NOT be keyed by bearer or source alone. + +The AS MUST give every package child a `grant_id` that matches the grammar `1*( ALPHA / DIGIT / "." / "_" / "~" / "-" )` (RFC 5234 ABNF; the characters `[A-Za-z0-9._~-]`). This constraint applies to package children only. + +The HTTP binding carries the selector in the `PDPP-Grant-Id` request header. Except for a child-discovery operation defined by the binding, a request made with a package token MUST contain exactly one `PDPP-Grant-Id` field line. A child-discovery operation MUST NOT require this header. For a Core client token the header is OPTIONAL. After normal HTTP field parsing removes leading and trailing whitespace, the value MUST match the `grant_id` grammar. The resource server MUST reject a request with more than one such field line, and a value that contains a comma, because an HTTP recipient can combine repeated field lines into one comma-separated value ([RFC 9110](https://www.rfc-editor.org/rfc/rfc9110) Section 5.3). The resource server compares the value with child `grant_id` values exactly and case-sensitively. A resource server that supports packages MUST reject a `PDPP-Grant-Id` header sent with a Core client token unless its value equals that token's `grant_id`. The MCP binding carries the selector in the `grant_id` tool argument ([MCP read profile](spec-mcp-profile), Section 3). + +### 5.4 Inactive selected child + +A selected child is inactive when it is revoked or expired, when it is past its read deadline, or when the token no longer carries it. When the package token is still active, a request that selects an inactive child fails with a terminal error. It is not an authorization challenge. + +In the HTTP binding, the resource server MUST return HTTP 403 with a `WWW-Authenticate: Bearer` challenge that has no `error="insufficient_scope"` parameter, and a structured error with type `permission_error` and code `package_child_inactive`. The MCP binding defines its own result ([MCP read profile](spec-mcp-profile), Section 3). + +A client MUST NOT start re-authorization automatically on `package_child_inactive`. Asking for replacement access is a separate authorization request that the owner reviews. The resource server MUST NOT substitute another child. + +When no child is active, the package token is inactive. The resource server then returns HTTP 401 with Bearer error `invalid_token`, as Core Section 8 requires for every inactive token. + +### 5.5 Issuance, refresh, and expiry + +The AS MUST consume every `single_use` child atomically with first package-token issuance. It MUST reject later access-token issuance against a consumed child, except a successor access token from the same refresh-token family inside the child's read window (Core Section 7). This restriction does not prohibit issuance or renewal of processing credentials under the child's permission-defining profile. + +The AS MAY issue a refresh token only when at least one child is `continuous` (Core Section 10). A refreshed access token carries every active `continuous` child and each active `single_use` child only until the child's read deadline, never after. Refresh never extends a read deadline or opens a second window. The AS MUST apply Core refresh rotation, family-reuse revocation, expiry, and revocation rules. Package-token expiry or revocation MUST deny all child reads. + +### 5.6 Revocation and disconnect + +Core Section 10 defines which credential revocation ends which grants. For a package: + +- Revoking the package refresh token, current or superseded, ends every child that its family covers and every access token issued under them. +- Revoking a package access token ends that token. It also ends the children only when no refresh-token family covers them. +- Withdrawing one child is a grant-level action at the AS, by owner action or a grant-management operation. It MUST NOT revoke the package credential or end another child. The package token stays active while another child is active. An owner's withdrawal of one child carries a disposition for that child only ([Ending paths](spec-core#ending-paths)). + +An AS that issues packages MUST offer a client-callable package disconnect. Disconnect ends every child of the package, the refresh-token family, and every access token issued under the package. It is distinct from revoking one access token, which can leave the family and the children active, and from withdrawing one child. + +Disconnect, and withdrawal of one child, end each affected child as Core revocation ends a grant, including its processing authority ([Read access and processing authority](spec-core#processing-authority)). Replay detection on the package refresh-token family invalidates tokens and does not by itself end a child's processing authority. + +Disconnect MUST work when the client no longer holds the current refresh token. The client presents any access token or refresh token that the AS issued for the package, active, expired, or superseded, and authenticates as Core's OAuth binding requires for token revocation. The AS MUST verify that the token was issued to that client for that package. Repeated disconnect calls do not reopen or otherwise change ended grant authority. Disposition handling is separate: a later authenticated `delete` applies to the package's held data even when some or all children have already ended. An existing effective erasure instruction is returned or retained without restarting its clocks. + +In the OAuth binding, the AS MUST advertise `pdpp_package_disconnect_endpoint` in its RFC 8414 metadata. The request follows [RFC 7009](https://www.rfc-editor.org/rfc/rfc7009) Section 2: a `POST` with `token` and optional `token_type_hint`. It MAY also carry `pdpp_disposition` and, with `delete`, `reported_at`, with Core's meaning, validation, and receipt-recording rules (Core Section 10). The AS checks current client authentication ([Grant lifecycle operation](spec-core#grant-lifecycle)) before applying the request's revocations. When that authentication authorizes the disposition, the AS MUST apply it to every child of the package, including children already ended. Without current client authentication, it ends the package as otherwise authorized but records no new disposition; the client's own erasure duty is unchanged. + +Before applying any effect of a request carrying an authorized disposition, the AS MUST durably retain the authenticated request's package scope, disposition, and credential binding. A matching retry MAY complete that recorded request after its own effects have revoked the credential. This continues the previously authorized operation; it MUST NOT authorize a new or different disposition with a historical credential. Pending child effects remain pending until recorded, and receipt of a pending result does not mean that those effects are complete. + +HTTP 200 means every requested effect that the request is authorized to perform has been durably recorded. For an authenticated request identifying a package, if any such effect remains pending, the AS MUST return HTTP 503 with `Retry-After` and a JSON body `{ "error": "temporarily_unavailable", "grants": [...] }`. The array MUST contain one `{ "grant_id", "status" }` entry per child, where `status` is `recorded` only when all requested effects for that child are durable, and `pending` otherwise. A retry MUST preserve recorded results and instruction clocks and attempt the pending effects. The AS MUST NOT disclose these per-child results to an unauthenticated caller. A client that disconnects at the owner's direction SHOULD send the disposition. + +## 6. Bounded presentation reads + +A resource server MAY expose bounded presentation operations over grant-authorized input. Supported behavior MUST be documented and MUST bind its conformance claim. Operations MAY include search, count, preview, or summary computation, but this profile defines no mandatory endpoint. + +Every record, field, identifier, count, search hit, preview, summary, or other derived fact is a disclosure. The resource server MUST compute it only from records and fields authorized by the applicable Core grant and MUST apply source, declaration snapshot, stream, instance, time, field, resource, lifecycle, and expiry constraints before computation. + +The resource server MUST NOT search a denied field and return merely projected hits, or use current declaration capabilities to widen or reinterpret an issued grant. If an authorized projection cannot be applied, it MUST redact the affected result or fail closed; error text MUST NOT reveal denied existence. + +A presentation result that identifies a record, including a search hit, preview, or fan-out entry, MUST give the record's `instance_id` with its `id`, using the handle from the applicable grant. A `resource_ref` or `blob_ref` in a presentation result MUST take the form Core Section 4 defines for served records: a resolved or redacted reference, and a `fetch_url` that carries `instance_id`. A presentation result MUST NOT contain `rs_instance` or the introspection `subject_id`. Identifiers for subjects, grantors, and instances MUST follow Core's [Pairwise identifiers](spec-core#pairwise-identifiers) rules, including its explicit owner-choice exception. Record keys and blob identifiers retain their Core representation. + +A presentation result MUST carry an `inputs` member whose value is a JSON array. The array MUST contain exactly one object for each distinct (`instance_id`, `stream`) pair the computation consulted, including pairs that matched nothing. Each object MUST contain `instance_id` and `stream` as strings and `last_success_at` as an RFC 3339 date-time string or null. `instance_id` is the client's pairwise handle from the applicable grant, and `stream` is the granted stream name. `last_success_at` is the value, as defined in Core [Freshness metadata](spec-core#freshness), that the computation used, or null when no timestamp is reportable. Array order has no meaning; when no pair was consulted, `inputs` is an empty array. `inputs` states which facts the result drew on. It is not an as-of or completeness guarantee, and a result MUST NOT replace it with a single blended timestamp. + +Each `last_success_at` in `inputs` follows Core's coarsening rule for client-token responses: the resource server truncates it to its declared `pdpp_freshness_granularity_seconds` and does not report it before its interval ends. A resource server that returns `inputs` MUST declare that granularity, as Core requires of one that attaches `freshness`. An `inputs` entry carries no failure time. + +In a fan-out envelope (Section 5.3), each entry that contains a bounded presentation result MUST carry that result's own `inputs`, computed under that child alone. A direct Core query result does not become a presentation result solely because it appears in a fan-out envelope. The envelope MUST NOT carry combined `inputs`. + +Free-text output, such as a generated summary, discloses all of its content. This profile does not guarantee that it reveals less than its inputs. + +A presentation result MUST NOT create a new declared source, durable derived dataset, independent-recipient disclosure authority ([Independent-recipient disclosure](spec-core#independent-recipient-disclosure)), processing permission, or grant authority. Durable derived data requires a separate declared source and authorization contract. This profile defines no action rights or mixed read-and-action rules; Core Section 8's [existing-permissions](spec-core#existing-permissions) boundary governs those operations. + +## 7. Conformance boundary + +Each optional feature is independently conformance-scoped. Owner-selection claims cover request, resolution, review, and result behavior. Package claims cover issuance, detail correlation, introspection, resource binding, child selection, inactive-child errors, refresh, and disconnect, including `pdpp_disposition`. Presentation claims cover only documented bounded operations, authorized-input computation, and `inputs` reporting. + +All claims remain subject to Core validation, authorization, disclosure, snapshot, revocation, expiry, result, and resource-server requirements. The implementation MUST fail closed whenever required authority, binding, status, projection, or complete result context is absent or ambiguous. Owner-selection and package claims MUST include the applicable Core authorization-privacy tests. diff --git a/spec-architecture.md b/spec-architecture.md index 7b23d4756..61876a8b1 100644 --- a/spec-architecture.md +++ b/spec-architecture.md @@ -1,7 +1,7 @@ # System Architecture: How the Spec Components Relate Status: Informative -Date: 2026-09-27 +Date: 2026-10-06 ## Components @@ -155,7 +155,7 @@ A request with `streams: [{ "name": "*" }]` is expanded at consent time into the When a client reads under a grant, how does it know whether the data is current? -Core Section 8 defines response-side freshness metadata: the resource server MAY attach `captured_at`, `status` (`current`, `stale`, `unknown`), and `last_attempted_at` to stream listings, stream metadata, and record-list responses. Implementations claiming Collection Profile support publish it (Core Section 9, Tier 2). Freshness reports local observation; it does not guarantee the source has not changed since `captured_at`. +Core Section 8 defines response-side freshness metadata: the resource server MAY attach a `freshness` array to stream listings, stream metadata, and record-list responses. The array has one entry for each instance that the grant, or the owner scope, authorizes for the stream. Each entry carries `last_success_at`, the time of the most recent successful collection or source confirmation relevant to the authorized scope. Client-token values are coarsened and carry no failure time; owner-token entries MAY carry `last_failure_at`. Freshness reports local observation; it does not guarantee the source has not changed since `last_success_at`. An empty result does not show that data is absent at the source (Core Section 8, Absence of records). Fulfillment remains an implementation choice: serve from storage, collect on a schedule, or collect before serving. The reference schedules collection per connection and serves stored records with freshness metadata. diff --git a/spec-core.md b/spec-core.md index 64356c10e..3935c33b1 100644 --- a/spec-core.md +++ b/spec-core.md @@ -1,7 +1,7 @@ # Personal Data Portability Protocol (PDPP) v0.1.0 Status: Normative draft -Date: 2026-09-29 +Date: 2026-10-14 --- @@ -44,7 +44,7 @@ Sections 4-8 define the protocol surfaces that implementations evaluate independ | [RFC 9396](https://www.rfc-editor.org/rfc/rfc9396) (RAR) | PDPP uses the `authorization_details` envelope for selection requests. The `type` URI is `https://pdpp.dev/data-access`. | | [RFC 6750](https://www.rfc-editor.org/rfc/rfc6750) (Bearer Token) | PDPP transports both owner tokens and client tokens as RFC 6750 Bearer Tokens on the wire. The resource server distinguishes token kind via `pdpp_token_kind` in the introspection response, not by token syntax. | | [RFC 7662](https://www.rfc-editor.org/rfc/rfc7662) (Token Introspection) | PDPP uses authenticated RFC 7662 token introspection where the authorization server and resource server are separated, so the resource server can resolve grant-bound tokens. Co-located deployments may use a local equivalent. | -| [RFC 9728](https://www.rfc-editor.org/rfc/rfc9728) (Protected Resource Metadata) | PDPP resource servers publish RFC 9728 protected resource metadata, so a client discovers the authorization server, the query base, and the supported token kinds from the resource itself rather than from prior configuration. Core defines four `pdpp_`-prefixed additional members (Section 8); the extension profiles define `capabilities`. | +| [RFC 9728](https://www.rfc-editor.org/rfc/rfc9728) (Protected Resource Metadata) | PDPP resource servers publish RFC 9728 protected resource metadata, so a client discovers the authorization server, the query base, and the supported token kinds from the resource itself rather than from prior configuration. Core defines five `pdpp_`-prefixed additional members (Section 8): four always required, and `pdpp_freshness_granularity_seconds` required when client-token responses carry `freshness`. The extension profiles define `capabilities`. | | [OAuth 2.0 Dynamic Client Registration](https://www.rfc-editor.org/rfc/rfc7591) (RFC 7591) | PDPP reuses the RFC 7591 client metadata vocabulary (`client_name`, `logo_uri`, `policy_uri`, and similar fields) for the consent display. A dynamic client registration endpoint is a deployment choice and is required only where deployments need it; Core functions without it. | | [Client ID Metadata Documents](https://datatracker.ietf.org/doc/draft-ietf-oauth-client-id-metadata-document/) (CIMD, IETF OAuth WG draft) | A client identifier that is itself an `https` URL the authorization server fetches to obtain RFC 7591-shaped client metadata, with no prior registration handshake. Control of the URL's domain is the trust root. CIMD is how deployed MCP clients present themselves: the MCP authorization specification revision 2025-11-25 states that authorization servers and clients SHOULD support CIMD and MAY support RFC 7591 dynamic client registration, which is retained for backward compatibility. Core treats a validated CIMD document as one source of validated binding metadata (Section 6) and its verified domain as a trust signal; the fetch and validation obligations belong to the OAuth binding rather than to Core. | | [SMART on FHIR](https://hl7.org/fhir/smart-app-launch/) | Follows the domain-profile-over-OAuth pattern PDPP adopts: OAuth handles authorization, and the profile adds a domain data model, consent semantics, and a conformance regime. SMART on FHIR reached ubiquity through regulatory adoption of SMART-on-FHIR-patterned API requirements (the ONC Cures Act rule). | @@ -53,10 +53,10 @@ Sections 4-8 define the protocol surfaces that implementations evaluate independ | [GNAP](https://www.rfc-editor.org/rfc/rfc9635) (RFC 9635) | GNAP is an IETF authorization protocol that revisits OAuth-style delegation with a new protocol design. Several design decisions are directly relevant to PDPP: (1) interaction modes beyond browser redirects (relevant to nonstandard authorization interaction patterns); (2) request continuation for multi-step consent negotiation (relevant to optional streams); (3) key-bound grants instead of bearer tokens (stronger security for ongoing personal data access); (4) built-in grant management with revocation and rotation (relevant to `continuous` access mode). PDPP's entity-scoped `client_display` already follows GNAP's pattern of carrying client display metadata inline in the request. PDPP separates its core artifacts from authorization-protocol bindings. OAuth 2.0 and RFC 9396 define the v0.1 binding. Other bindings, including GNAP, may be specified as adoption warrants. For key-bound tokens specifically, DPoP (RFC 9449) offers an OAuth-native path to GNAP-style sender-constrained tokens and is a candidate optional hardening profile for v0.2. | | [Solid](https://solidproject.org) | Solid takes the full re-architecture approach: personal data moves into user-controlled pods with RDF/Linked Data semantics, which requires source platforms to adopt the model or users to migrate off-platform. PDPP instead layers on existing OAuth infrastructure and bootstraps data supply through the Collection Profile, without requiring source platforms to adopt anything. | | [ODRL](https://www.w3.org/TR/odrl-model/) (W3C Recommendation) | ODRL expresses permissions, prohibitions, and duties as machine-readable policies. PDPP does not use ODRL for authorization. The resource server enforces a PDPP grant on each read. A policy that travels with disclosed data cannot by itself guarantee enforcement after disclosure, the same limit Core states for `retention` (Section 11). | -| [DPV](https://w3id.org/dpv) (W3C Data Privacy Vocabularies and Controls Community Group) | DPV defines shared terms for purposes, legal bases, and processing. `purpose_code` accepts any absolute URI (Appendix A), so a DPV purpose IRI can be used as a purpose code. PDPP defines its own registry for the purposes its consent rules name. | +| [DPV](https://w3id.org/dpv) (W3C Data Privacy Vocabularies and Controls Community Group) | DPV defines shared terms for purposes, legal bases, and processing. `purpose_code` accepts any absolute URI (Appendix A), so a DPV purpose IRI can be used as a purpose code. PDPP defines its own purpose registry. DPV treats model training as processing, and PDPP likewise carries AI training as a processing permission, not a purpose (Section 6). | | [Data Transfer Project](https://github.com/dtinit/data-transfer-project) (DTI) | PDPP and DTI are complementary. The Data Transfer Project handles transfer mechanics, and DTI's stated position is that there is "no silver bullet" for portability: multiple approaches coexist. DTI's Data Trust Registry (post-pilot, 2026) addresses who is trusted: it vets services seeking access to platforms' portability interfaces so that platforms can rely on shared trust signals. PDPP addresses what was consented and how it is enforced (the grant and the resource server interface); a trust registry and PDPP's consent semantics compose rather than compete. The two protocols can chain. See Appendix B. | | [Airbyte](https://airbyte.com) / [Singer](https://www.singer.io) | PDPP borrows the RECORD/STATE checkpoint pattern for incremental sync. This record and state-checkpoint lineage informs the Collection Profile companion specification; it appears here for reader orientation and is informative for Core. | -| [GDPR](https://eur-lex.europa.eu/eli/reg/2016/679/oj) | PDPP implements data minimization through stream and field selection. It also carries machine-readable purpose declarations (`purpose_code`) that support consent display, local policy, and implementation-defined audit or transparency mechanisms, with an explicit protocol-level consent rule for `ai_training`. The internal version history required for incremental sync may support implementations that choose to expose historical access features to users. Whether such exposure is required is outside the scope of this specification. This alignment is informative only and is not a required v0.1 capability. | +| [GDPR](https://eur-lex.europa.eu/eli/reg/2016/679/oj) | PDPP implements data minimization through stream and field selection. It also carries machine-readable purpose declarations (`purpose_code`) that support consent display, local policy, and implementation-defined audit or transparency mechanisms, and a separately approved processing permission for AI training (Section 6). The internal version history required for incremental sync may support implementations that choose to expose historical access features to users. Whether such exposure is required is outside the scope of this specification. This alignment is informative only and is not a required v0.1 capability. | | [DMA](https://eur-lex.europa.eu/eli/reg/2022/1925/oj) | The `continuous` access mode enables ongoing portability aligned with the DMA's requirements. Article 6(9) requires effective portability with continuous and real-time access to the end user's data; PDPP's continuous grants and incremental sync map to that requirement. This alignment is informative only and is not a required v0.1 capability. | | [EU Data Act](https://eur-lex.europa.eu/eli/reg/2023/2854/oj) (Regulation 2023/2854) | The Data Act's Article 5(1) flow, where a user directs a data holder to make data available to a third party, is the same triangle as PDPP's owner, source, and client. Article 2(12) defines the user as a natural or legal person, matching PDPP's subject-neutral owner. It applies from 12 September 2025, requires access by design for connected products placed on the market after 12 September 2026, and names no protocol. | @@ -90,7 +90,7 @@ These roles may be co-located in a single deployment (e.g., a personal server ac | Role | Responsibility | |------|---------------| -| **Authorization Server** | Issues and manages grants. Validates selection requests against retained source declaration snapshots. Tracks grant lifecycle (active, expired, revoked). | +| **Authorization Server** | Issues and manages grants. Validates selection requests against retained source declaration snapshots. Tracks grant lifecycle (active, expired, revoked) and answers lifecycle queries from clients that hold data. | | **Resource Server** | Stores records as flat relational streams. Serves records to clients filtered by grant parameters. | The [PDPP Collection Profile](spec-collection-profile) defines a third role: @@ -101,9 +101,9 @@ The [PDPP Collection Profile](spec-collection-profile) defines a third role: In many deployments, a single **personal server** fills all three roles. The spec uses "personal server" when referring to a combined deployment, and the specific role name when the distinction matters. -**Note on the Authorization Server interface:** This spec defines the resource server interface normatively because cross-deployment interoperability requires it: a client written against the interface works with any conformant resource server regardless of who operates it or where data lives. The authorization server interface is not normatively specified in v0.1 because user-facing authorization flows are deployment-specific. The reference implementation uses the OAuth authorization code flow with RFC 9396 authorization_details for client grants, and OAuth device authorization for owner tokens. +**Note on the Authorization Server interface:** User-facing authorization interaction remains deployment-specific. Request resolution, the OAuth token result, and AS-to-RS token resolution are normative contracts. Core does not prescribe the consent screen layout or the owner's authentication method. -**Token resolution:** User-facing authorization flows are deployment-specific and are not normatively specified in v0.1. However, when the AS and RS are deployed separately, the AS-to-RS token-resolution contract is normative: the RS MUST authenticate to the RFC 7662 introspection endpoint and resolve the complete grant enforcement context from its response. The RS MUST enforce the request from that response and MUST NOT make a second AS lookup. For co-located deployments, a local equivalent (shared database or function call) is acceptable. Self-contained JWTs may be used as an optimization but MUST NOT be the sole revocation mechanism (see Section 10). +**Token resolution:** When the AS and RS are deployed separately, the AS-to-RS token-resolution contract is normative: the RS MUST authenticate to the RFC 7662 introspection endpoint and resolve the complete grant enforcement context from its response. The RS MUST enforce the request from that response and MUST NOT make a second AS lookup. For co-located deployments, a local equivalent (shared database or function call) is acceptable. Self-contained JWTs may be used as an optimization but MUST NOT be the sole revocation mechanism (see Section 10). ### Trust registry queries {#trust-registry-queries} @@ -115,17 +115,23 @@ An authorization server records the trust signal it relied on — subject, role Core does not define the registry, transport, recognition mechanism, or withdrawal propagation. A server that consults no registry remains conformant because registry answers inform local policy and never replace the owner's grant. ToIP's Trust Registry Query Protocol is an intended future profile binding, not a Core requirement. -### Data concepts +### Data concepts {#data-concepts} | Term | Definition | |------|-----------| | **Grant** | An immutable consent artifact specifying what data a client may access, under what constraints. | | **Stream** | A named collection of records with a schema, primary key, and optional cursor field. Stream names are source-local (e.g., `messages`). The fully qualified identifier is an ordered pair `(source.id, stream_name)`, used in cross-source references and storage. Example: `("https://registry.pdpp.dev/connectors/spotify", "top_artists")`. | +| **Instance** | One connected account, device, or profile of the owner at a source, for example one of two Spotify accounts. A grant names instances by opaque handles (`instance_ids`). One handle names an instance in every stream of its source. Each stored record belongs to exactly one instance. | | **Record** | A single data object within a stream. | | **Connector** | A program that collects data from a data source, used when data is collected rather than served natively. One of possibly several producers of a source's streams. Defined in the Collection Profile. | | **Source Declaration** | A source's versioned declaration of its identity, publisher, streams, schemas, consent surface, selection capabilities, and Resource Server query capabilities. It does not define connector acquisition or execution. | | **Selection Request** | A client's request for specific data, expressed as RFC 9396 `authorization_details`. | | **View** | An optional named field set a source declaration may define for a stream, composed from fields declared in the stream schema. When a client requests by view name, the resulting grant records the resolved field list, which is authoritative. Declared views are advisory; the authorization server is authoritative for views used in consent UI and issued grants. | +| **Processing permission** | Authority, carried in a grant, for an operation on disclosed data that read access alone does not authorize, such as AI training. See [Processing permissions](#processing-permissions). | +| **PDPP data** | Data obtained through PDPP, or data derived from it, including through successive transformations. Derivatives include labels, synthetic examples, embeddings, indexes, caches, and outputs generated using PDPP data. A model output is derived from an owner's PDPP data only when that data was an input to producing that output. Earlier use of an owner's data to train the model does not, by itself, make the output a derivative of that owner's data. | +| **Held data** | The PDPP data that a client, or a party acting for it, holds and that the client obtained under a given grant or derived from data so obtained. See [Held data after a grant ends](#held-data). | +| **Independent recipient** | A party other than the owner that receives PDPP data for an operation in which it does not act for the client under [Downstream holders](#downstream-holders). A party's role is determined for that operation; the same party can act for the client in another operation. | +| **Erasure instruction** | The owner's durable instruction that a client stop using and delete the held data of a grant. See [Erasure](#erasure). | ### Requirements Language {#requirements-language} @@ -133,7 +139,7 @@ The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "S This document is normative except where content is explicitly marked as an example, a note, or otherwise non-normative. -This is the only normative document for PDPP Core v0.1 conformance. A profile defines no Core requirement; a future profile may define a separate named conformance claim only if its own status says so. The [PDPP Collection Profile](spec-collection-profile) and [PDPP Source Declaration Discovery and Trust](spec-discovery-and-trust) are informative and define no conformance requirements of their own. +This is the only normative document for PDPP Core v0.1 conformance. A profile imposes no requirement on an implementation that does not claim it. A future profile may define a separate named conformance claim only if its own status says so. Core can make support for a Core-defined value depend on such a claim: an implementation that supports a processing permission MUST conform to the permission's defining profile (Section 6). The [PDPP Collection Profile](spec-collection-profile) and [PDPP Source Declaration Discovery and Trust](spec-discovery-and-trust) are informative and define no conformance requirements of their own. --- @@ -195,7 +201,9 @@ PDPP therefore defines no delegated-grant, sub-grant, or grant-chaining construc Only live passthrough is bounded by the upstream grant: when the personal server does not hold a copy and reads from the platform to fulfill a downstream request, it MUST stay within the upstream grant. This limit does not constrain a fresh grant for owner-held data. A downstream PDPP token is never forwarded upstream. -**Onward transfer is prohibited.** A recipient MUST NOT transfer its token or let an ungranted party exercise it. +**Token transfer is prohibited.** A recipient MUST NOT transfer its token or let an ungranted party exercise it. + +A client's disclosure of held PDPP data to an independent recipient is governed by [Independent-recipient disclosure](#independent-recipient-disclosure). This is distinct from an RS serving owner-held data under a fresh grant to the receiving client, as described above. A different topology — the owner running their own authorization server in front of a platform's data, so that the platform holds the data but the owner's server decides who may read it — is not introduced by this specification. It is the arrangement UMA describes, it is not the arrangement above, and it is recorded as deferred rather than left ambiguous. @@ -238,6 +246,16 @@ Approximately 95% of personal data by volume is `append_only`. The remaining 5% An authorization server MUST reject a declaration containing an unrecognized `streams[].semantics` value. A resource server MUST NOT interpret an unrecognized stream semantic as `append_only` or `mutable_state`. A later version can add semantic types; an implementation that predates one does not apply the wrong write and sync behavior to it. +### Full records and disclosed projections + +A stream schema describes a full record before disclosure projection. For a client token, the StreamGrant's `required_fields` is the frozen consent floor defined in Sections 5 through 7. For a client-token read, the RS MUST include those fields whenever it returns that record's `data` and the stored record version has a value for them. A required field without a stored value stays absent. A tombstone carries no `data` and follows the tombstone shape defined in this section. + +The RS MUST construct disclosed `data` from only the top-level members permitted by the grant and the request-time field selection. Missing authorized optional members remain absent. The RS MUST NOT insert nulls or fabricated values for withheld members. A client MUST NOT validate a projected `data` object as though it were the full stream record. + +Envelope identifiers remain part of the record contract. The AS MUST disclose this fact during owner review. Withholding an identifier from `data` does not hide a matching identifier in the envelope. If envelope disclosure is unacceptable, the AS MUST omit an optional stream or refuse issuance for a required stream. + +An RS unable to serve a requested projection without changing the meaning of the disclosed data MUST refuse that read with HTTP 403 `disclosure_unavailable`. It MUST NOT repair the projection by disclosing unauthorized fields. + ### Incremental sync {#incremental-sync} Every stream supports incremental sync. The resource server maintains internal change history for it: the order in which it ingested and changed records, version history for `mutable_state` streams, and enough deletion information to emit tombstones. This is an implementation detail: the protocol surface is a standard cursor-based query that returns the changes since a given token (see [Section 8](#resource-server-interface)). The change history is not exposed as a separate stream. @@ -252,7 +270,7 @@ This promise covers field values, not membership. Under a time-bounded or resour **Snapshot model:** `changes_since` returns the full current state of every record not visible at h0 and visible at h1, and of every record visible at both whose grant-authorized projection changed, plus tombstones. It does not return field-level diffs. The client receives a complete record object for any record that changed. -**Visibility:** A record is *visible* at a horizon if it exists at that horizon and passes every restriction of the query context at that horizon. For a client token, these are the grant's stream, `instance_ids`, `resources`, and `time_constraint`. For an owner token, they are the owner scope and any request filter. A `changes_since` session from horizon h0 to horizon h1 returns: +**Visibility:** A record is *visible* at a horizon if it exists at that horizon and passes every restriction of the query context at that horizon. For a client token, these are the grant's stream, `instance_ids`, `resources`, and `time_constraint`. For an owner token, they are the owner scope and any request filter. Within a stream, a record is identified by its instance and its canonical key (see RECORD envelope, Record identity below). A `changes_since` session from horizon h0 to horizon h1 returns: | At h0 | At h1 | Result | |---|---|---| @@ -265,7 +283,7 @@ The session compares only the two horizons. The resource server MUST emit a tomb Visibility at h0 uses the record's version at h0. For a deleted record, the h0 version establishes visibility at h0, and deletion evidence establishes only the fact and time of the deletion; the `data` of the delete directive is never used. The resource server MUST retain the state needed to determine visibility at every unexpired horizon. If it cannot determine that state, it MUST fail the session with 410 `cursor_expired`. -**Sync guarantee:** With these rules, two conforming resource servers that hold the same records produce the same synced copy. The guarantee covers only a copy that starts at `beginning` and is updated by later `changes_since` sessions. A client that also keeps records from other reads, such as a get by ID between sessions, reconciles them itself; a get by ID returns 404 once the record is not visible. A client MUST treat a tombstone for an ID it does not hold as a no-op. +**Sync guarantee:** With these rules, two conforming resource servers that hold the same records produce the same synced copy. The guarantee covers only a copy that starts at `beginning` and is updated by later `changes_since` sessions. A client that also keeps records from other reads, such as a get by ID between sessions, reconciles them itself; a get by ID returns 404 once the record is not visible. A client MUST treat a tombstone for a record it does not hold as a no-op. **Starting a sync:** A client starts incremental sync with `changes_since=beginning`. `beginning` stands for an empty horizon at which no record is visible, so the first session returns every visible record and no tombstones. It is not a retained snapshot: it never expires, and it is bound to a grant and query context only when a request uses it. After a completed `changes_since=beginning` session, the client MUST replace its copy of the stream with that session's result. This applies to every restart, not only a restart after `cursor_expired`. @@ -279,6 +297,7 @@ Visibility at h0 uses the record's version at h0. For a deleted record, the h0 v { "object": "record", "id": "canonical-key-string", + "instance_id": "inst_K4wq8Rn2", "stream": "playlists", "deleted": true } @@ -292,6 +311,7 @@ For an owner token, a tombstone also carries `removal`, and for a deletion `dele { "object": "record", "id": "canonical-key-string", + "instance_id": "inst_Zp5rT2mA", "stream": "playlists", "deleted": true, "removal": "deleted", @@ -302,7 +322,7 @@ For an owner token, a tombstone also carries `removal`, and for a deletion `dele `removal` is `deleted` when the record was deleted, and `left_query` when the record still exists but no longer passes the owner's query context, for example a range filter. `deleted_at` and `emitted_at` are present only when `removal` is `deleted`. The owner owns the data, so the reason is not hidden from them. -Tombstones use the same `object: "record"` envelope as regular response records, with `deleted: true`. The `id` field is the canonical key string (see RECORD envelope, Compound key encoding below). +Tombstones use the same `object: "record"` envelope as regular response records, with `deleted: true`. The `id` field is the canonical key string (see RECORD envelope, Compound key encoding below), and `instance_id` names the record's instance. A tombstone signals that a record left the client's view of the stream. For subset or derived streams this means membership removal; it does not assert that the source record was deleted. See [Derived subset streams](#predicate-based-grant-scoping) (Section 12) for the non-normative discussion of this stream shape. @@ -352,6 +372,10 @@ RECORD is the universal data envelope. It is used in the Collection Profile and **Record identity:** For any record, the values of the `data` fields named by the stream's `primary_key` MUST match the values in the `key` envelope field (in order). A resource server or profile-defined write interface MUST reject a record before storage when those values disagree. The Collection Profile defines the HTTP error for its ingest endpoint. +A resource server stores each record under exactly one instance. The canonical key is unique only within one instance of a stream: two instances can hold records with the same key, for example the same playlist in two accounts. Within a stream, a record is therefore identified by its `instance_id` and its canonical key. Core defines no ingest path, so it does not define how a record is assigned to an instance. + +**Response records:** A query response serves each record as an object with `object: "record"`, `id` (the canonical key string), `instance_id`, `stream`, `data`, and `emitted_at`. A tombstone uses the same object with `deleted: true` (see Tombstones above). `instance_id` is the opaque handle of the record's instance, and every served record and tombstone carries it. For a client token, it is the handle that the grant lists for that instance. For an owner token, it is the owner's handle for that instance, and every owner-token response uses the same value. A client MUST identify a record within a stream by its `instance_id` and `id` together. + ### Timestamps Two timestamp concepts appear in records: @@ -385,7 +409,7 @@ Streams reference each other via foreign key fields in `data`: } ``` -The SourceDeclaration declares `primary_key` per stream. Foreign key relationships are declared in its `relationships` field (see [Section 5](#source-declaration)). +The SourceDeclaration declares `primary_key` per stream. Foreign key relationships are declared in its `relationships` field (see [Section 5](#source-declaration)). A foreign key refers to a record in the same instance. ### Binary data (blob_ref) @@ -410,7 +434,7 @@ Binary data (photos, videos, audio, documents) is not inlined in records. The re } ``` -`mime_type` MUST be a valid IANA media type (see [IANA Media Types](https://www.iana.org/assignments/media-types/)). Record producers emit `blob_ref` without a `fetch_url`. The resource server injects `fetch_url` at read time when serving records via the query API. +`mime_type` MUST be a valid IANA media type (see [IANA Media Types](https://www.iana.org/assignments/media-types/)). Record producers emit `blob_ref` without a `fetch_url`. The resource server injects `fetch_url` at read time when serving records via the query API. A `blob_id` is unique only within one instance, so the `fetch_url` carries the blob's `instance_id` (see Get a blob in Section 8). ### Cross-stream references (resource_ref) @@ -431,6 +455,22 @@ When a record references a record in a different stream on the same resource ser } ``` +A record producer emits `resource_ref` without `instance_id`. When `source_id` is the referencing record's source, the target is in the referencing record's instance. Core does not define how to resolve the target instance of a reference to another source (Section 12). + +At read time, in the same way that it adds `fetch_url` to a `blob_ref`, the resource server serves each `resource_ref` in one of two forms. It serves the resolved form, the reference with `instance_id` added, only when the target is in the referencing record's source and is authorized under the requesting token. For a client token, the target MUST pass every constraint of the same grant for the target stream: instance, `resources`, time constraint, and field access to the target's key. For an owner token, the target MUST fall within its subject, source, connection, and operation scope; no client grant is required or synthesized. The value is the target instance's handle, chosen as for response records. Otherwise it serves the redacted form, which has exactly `source_id`, `stream`, and `redacted: true`, and no `record_id` or `instance_id`: + +```json +{ + "source_id": "https://registry.pdpp.dev/connectors/instagram", + "stream": "media", + "redacted": true +} +``` + +For a client token, the token may read the target's instance only when the grant lists that instance's handle for the target stream. In v0.1, the resource server serves every reference to another source in the redacted form. The redacted form replaces the reference in place, and the resource server never drops the field that holds it, even when the stream schema requires `record_id` inside that field. No other form is served. A client MUST accept a redacted form wherever a `resource_ref` can appear, and MUST treat it as a reference that it cannot follow. + +For `changes_since`, the comparison projection includes each `resource_ref` in the fields used to determine eligibility, after resolution or redaction. The RS MUST evaluate each reference and its target at each horizon where the referring record is visible. It MUST return the referring record when this projection changes, even if the referring record's stored fields do not. All pages resolve references against h1; an ordinary target edit after the first page affects only the next session. If a target is deleted after the first page, later pages MUST redact references to it. The RS MUST record each referring record that the session serves with a reference redacted for this reason. The next session under the same grant and query context MUST return each such record that is visible at its horizon, projected as of that horizon, even if its projection is the same at both horizons. For an owner token, the same grant means the same subject and effective owner scope. This is an exception to the projection-change rule in [Incremental sync](#incremental-sync). Such a record that is not visible at the next horizon follows the tombstone rules. The RS MUST retain the target, dependency, and redaction history needed for this evaluation, or return 410 `cursor_expired`. + --- ## 5. Source Declaration {#source-declaration} @@ -554,8 +594,8 @@ Each source publishes a `SourceDeclaration` describing its identity, publisher, | `streams[].display` | Optional consent-surface metadata. See [Stream display metadata](#stream-display). | | `streams[].semantics` | `append_only` or `mutable_state`. | | `streams[].schema` | JSON Schema for the record's `data` field. `primary_key` and `cursor_field` MUST reference fields declared here. | -| `streams[].primary_key` | Fields that uniquely identify a record within the stream. | -| `streams[].cursor_field` | Field used for logical record ordering in ordinary list reads. `changes_since` uses a separate RS change-order position, not `cursor_field`. List reads sort by `(cursor_field, primary_key)`, with null or absent cursor values sorting after present values. A cursor is an opaque token the server issues, encoding a logical sort position in the stream. | +| `streams[].primary_key` | Fields that uniquely identify a record within one instance of the stream (see Record identity in Section 4). | +| `streams[].cursor_field` | Field used for logical record ordering in ordinary list reads. `changes_since` uses a separate RS change-order position, not `cursor_field`. List reads sort by `(cursor_field, instance_id, primary_key)`, with null or absent cursor values sorting after present values. A cursor is an opaque token the server issues, encoding a logical sort position in the stream. | | `streams[].consent_time_field` | The temporal consent boundary: the field against which `time_range` is evaluated. Absent means `time_range` is not applicable to this stream. MUST reference a top-level field declared in the schema with format `date` or `date-time` (see [consent_time_field](#consent-time-field)). | | `streams[].consent_time_content_may_exceed` | Optional boolean, default `false`. `true` means a record can contain data from outside its own `consent_time_field` value. The AS MUST reject a non-boolean value. See [consent_time_field](#consent-time-field). | | `streams[].selection` | Which selection parameters this stream supports (`fields`, `resources`). Time-range capability is derived from `consent_time_field` presence; absent means not time-range-capable. The AS MUST reject grants that request `time_range` on a stream without a `consent_time_field`, or that request an unsupported selection parameter. The `fields: ["*"]` marker is always supported. | @@ -640,7 +680,7 @@ Streams that cannot define a stable `consent_time_field` simply omit it. The abs |-------|-------------| | `name` | Relation name (used in `expand[]` on the query API). | | `stream` | The related stream name. | -| `foreign_key` | The field on the related stream that references this stream's primary key. | +| `foreign_key` | The field on the related stream that references this stream's primary key in the same instance. | | `cardinality` | `has_many` or `has_one`. | ### Views {#views} @@ -667,7 +707,7 @@ Adding a field, view, stream, or capability to a later declaration never widens An authorization server accepts a source declaration only through explicit owner or operator onboarding, an installed catalog, an accepted registry entry, or explicit local provisioning. A client MUST NOT introduce a new source authority or declaration URI during authorization. -For a `provider_native` source, `source.id` MUST be identical to the protected-resource identifier the authorization server has already accepted for that resource. The authorization server MUST reject any mismatch before consent or grant issuance. +For a `provider_native` source, `source.id` MUST be identical to the protected-resource identifier the authorization server has already accepted for that resource. The authorization server MUST reject any mismatch before consent or grant issuance. This check depends only on the AS's own resource configuration, not on protected owner state ([Authorization privacy boundary](#authorization-privacy)). `publisher.id` is an unauthenticated claim unless an accepted channel or configured mapping binds that publisher to the declaration. Without such a binding, the authorization server MUST NOT rely on `publisher.id` for source acceptance, attribution, redirect policy, or any other trust decision. @@ -712,7 +752,7 @@ A client requests specific personal data by including `authorization_details` in "name": "top_artists", "necessity": "required", "view": "basic", - "instance_ids": ["spotify-account-a"], + "instance_ids": ["inst_K4wq8Rn2"], "time_range": { "since": "2025-09-28T00:00:00Z" } }, { @@ -791,8 +831,8 @@ If rendered on the final owner review surface, `client_claims` MUST be normalize PDPP uses three primary semantic classes across selection requests and grants: -- **Protocol-enforced constraints:** Values the AS and/or RS actually validate or enforce, such as stream selection, field projection, `time_range`, `resources`, and `access_mode`. -- **Structured policy declarations:** Machine-readable statements that matter for consent, local policy, and implementation-defined audit or transparency mechanisms, but are not generally self-enforcing at the protocol layer. In v0.1 this includes `purpose_code`, `purpose_description`, and `retention`, with one explicit exception: `https://pdpp.dev/purpose/ai_training` adds a protocol-level consent requirement. +- **Protocol-enforced constraints:** Values the AS and/or RS actually validate or enforce, such as stream selection, field projection, `time_range`, `resources`, `access_mode`, and the closed `processing_permissions` set. +- **Structured policy declarations:** Machine-readable statements that matter for consent, local policy, and implementation-defined audit or transparency mechanisms, but are not generally self-enforcing at the protocol layer. In v0.1 this includes `purpose_code`, `purpose_description`, and `retention`. None of them confers a processing permission. - **Attributed client claims:** Client-authored statements that may matter to the user but are not protocol facts. In v0.1 this is `client_claims`. `client_display` is a separate category: requester identity metadata used to identify who is asking, not a grant constraint. Inline values may be client-asserted, but the AS renders them under its own resolution and trust policy. @@ -804,14 +844,17 @@ PDPP does not standardize consent screen layout, visual design, or copywriting. | Parameter | Type | Required | Status | Description | |-----------|------|----------|--------|-------------| | `source` | object | yes | Protocol-enforced | Source binding. `id` is required and is the stable absolute URI authorization identity for the data surface. A request carries `id` alone: provenance is derived by the authorization server from the accepted declaration, not asserted by the client. | -| `purpose_code` | URI | yes | Structured policy declaration | Machine-readable purpose (absolute URI). `purpose_code` identifies the requested data-use purpose; clients SHOULD NOT substitute an agreement or terms-document identifier for it. See Appendix A for the initial registry. The AS MUST accept any syntactically valid absolute-URI purpose code. For unrecognized codes, the AS MUST display `purpose_description` if present, or the raw URI if not, and MUST NOT reject the request solely because the purpose code is unrecognized. Consent properties associated with purpose codes in the registry are advisory, not protocol-enforced, with the exception of `https://pdpp.dev/purpose/ai_training` (see below). | -| `purpose_description` | string | no | Structured policy declaration | Human-readable purpose, displayed to the user during consent. Clients SHOULD provide this field. When present, the AS MUST display it. For standard purpose codes, the AS MAY display a human-readable label from the registry when `purpose_description` is absent. | +| `purpose_code` | URI | yes | Structured policy declaration | Machine-readable purpose (absolute URI). `purpose_code` identifies the requested data-use purpose; clients SHOULD NOT substitute an agreement or terms-document identifier for it. See Appendix A for the initial registry. The AS MUST accept any syntactically valid absolute-URI purpose code. For unrecognized codes, the AS MUST display `purpose_description` if present, or the raw URI if not, and MUST NOT reject the request solely because the purpose code is unrecognized. Consent properties associated with purpose codes in the registry are advisory, not protocol-enforced. A purpose code never confers a processing permission. | +| `purpose_description` | string | no | Structured policy declaration | Human-readable purpose, displayed to the user during consent. Clients SHOULD provide this field. When present, the AS MUST display it. For standard purpose codes, the AS MAY display a human-readable label from the registry when `purpose_description` is absent. A detail that carries the AI training permission MUST include it ([AI training consent](#ai-training-consent)). | | `access_mode` | enum | yes | Protocol-enforced | `single_use` or `continuous`. See [Section 7](#grant). | +| `processing_permissions` | string[] | no | Protocol-enforced at issuance time | Unique absolute-URI processing-permission identifiers. Absent or empty requests no processing permission. See [Processing permissions](#processing-permissions). | | `retention` | object | no | Structured policy declaration | Requested retention constraints: `{ max_duration, on_expiry }`. | | `streams` | StreamRequest[] | yes (unless `selection_preset` is used) | Protocol-enforced | Requested streams with per-stream parameters. | | `selection_preset` | string | no | Protocol-enforced at issuance time | Reference to a SourceDeclaration preset, as an alternative to explicit streams. | | `client_claims` | object | no | Attributed client claim | Client-authored, non-enforceable claims about this request. See [Client claims](#client-claims). | +**Unknown members.** As RFC 9396 Section 5 requires, the AS MUST reject a detail that carries a member that neither Core nor a profile the AS supports defines for that detail type. The OAuth/RAR binding returns `invalid_authorization_details`. The AS MUST NOT ignore the member. A future control contract therefore cannot be issued by an AS that does not implement it. + #### Source kinds {#source-kinds} These are the two provenance classes an authorization server derives and carries forward. They are defined here because this is where a reader meets the source binding, not because a client sends one. @@ -825,9 +868,67 @@ A selection request does not carry `source.kind`. The authorization server deriv An authorization server MUST reject a declaration containing an unrecognized `source.kind`. A resource server MUST NOT interpret an unrecognized grant `source.kind` as a known provenance class. A client that reads an unrecognized `source.kind` in a grant MUST NOT treat it as either known value; it MAY reject the grant as unsupported. A later version can add provenance classes; an implementation that predates one does not misread it as a known class. +#### Processing permissions {#processing-permissions} + +A processing permission authorizes an operation on disclosed data that read access alone does not authorize. A selection request and a grant carry processing permissions in `processing_permissions`, a set of unique absolute-URI identifiers. Absent or empty means no processing permission. An issued grant carries the member only when the set is non-empty. `processing_permissions` is a Core field, not an extension. A purpose code, `purpose_description`, `client_claims`, `retention`, or extension never confers a processing permission. + +Independent-recipient disclosure is an operation that requires a covering processing permission ([Independent-recipient disclosure](#independent-recipient-disclosure)). This version defines no processing permission for that operation. A purpose code or purpose description does not authorize it. + +Each identifier has one defining specification, which states the operation the permission covers and how a recipient maintains and exercises the authority. Core defines one identifier: + +| Identifier | Operation | Defining specification | Status | +|---|---|---|---| +| `https://pdpp.dev/processing/ai_training` | [AI training](#ai-training) | PDPP AI Training Profile (forthcoming) | Reserved and unsupported until that profile is published and its registration is approved | + +**Closed issuance.** The AS MUST reject a detail whose `processing_permissions` is not an array of absolute URIs, or contains a duplicate, unknown, or unsupported value. The OAuth/RAR binding returns RFC 9396 `invalid_authorization_details`. The AS MUST NOT ignore, substitute, or narrow such a value, and MUST NOT issue an ordinary grant in place of the detail. + +**Example.** Until the AI Training Profile is registered, every AS receives this detail as unsupported: + +```json +{ + "type": "https://pdpp.dev/data-access", + "source": { "id": "https://registry.pdpp.dev/connectors/spotify" }, + "purpose_code": "https://pdpp.dev/purpose/personalization", + "purpose_description": "Train an on-device model that ranks concerts for Concert Finder", + "access_mode": "single_use", + "processing_permissions": ["https://pdpp.dev/processing/ai_training"], + "streams": [{ "name": "play_events", "fields": ["*"] }] +} +``` + +The AS returns `invalid_authorization_details`. It issues no training grant and no ordinary grant in its place. + +**Discovery.** An AS lists the permissions it supports in `pdpp_processing_permissions_supported`, an array member of its [RFC 8414](https://www.rfc-editor.org/rfc/rfc8414) authorization-server metadata. Absent or empty means the AS supports none. An AS MUST NOT advertise or grant a permission unless it implements the permission's complete defining contract. A client MUST NOT request a permission that the AS does not advertise. + +**Registration.** Only this specification, or a profile registered under a Specification Required policy ([RFC 8126](https://www.rfc-editor.org/rfc/rfc8126) Section 4.6), defines a processing permission. A registration gives the identifier, its stable semantics, and exactly one defining profile and version, and the decision to approve it is publicly recorded. A client, deployment, or extension cannot define a processing permission. The registered defining profile and version are an immutable normative reference for the permission identifier. Registry maintainers MUST NOT replace that reference with a different profile or version. A grant retains the authority and owner protections of that registered version, including for subsequent issuance or renewal of processing authority. Publishing a later profile version does not change this binding. A profile revision MUST NOT widen that authority or reduce those protections. Publishing a revision MUST NOT retroactively invalidate previously issued processing authority or make conduct permitted by the bound version non-conformant. An AS MAY issue shorter-lived or more restricted processing authority when the bound version permits it. Binding grants to a different defining profile or version requires a new permission identifier and fresh owner approval. + +**Registration test.** A registration MUST identify every result of the permitted operation that survives the [erasure](#erasure) duty. Where such a result may retain or reveal an owner's data, the defining profile MUST bound cessation of the operation to at most 1 hour. That bound runs from the end of the grant, or from the effective time of an erasure instruction covering the operation's inputs. It MUST hold without delivery of any message to the client, and over the whole execution interval of the operation. A check made once when work starts does not meet it. The defining profile MUST also make every issuance of processing authority depend on the continued eligibility of each acquisition copy the authority covers: no effective erasure instruction covers the copy, and the client may still hold and process it. When an advance instruction has a known future effective time, no processing authority for the covered copy may outlast that time. To make this check possible, the defining profile MUST make each processing credential name the acquisition grants whose held data it covers, and MUST make the processor refuse an input acquired under any grant the credential does not name. A credential that names no acquisition grant covers only data acquired under its own grant. + +For a permission that covers independent-recipient disclosure, the defining profile MUST specify the recipients or recipient classes the owner approves. It MUST specify the data and disclosure operations that approval covers. It MUST define the receiving parties' obligations and the evidence of their acceptance. It MUST define which effects of withdrawal and erasure reach those parties. It MUST identify any copy or result that remains usable after those effects. It MUST require the AS to show the owner those limits before approval. + +This paragraph does not waive the existing registration test or its cessation bound. + +**Consent and evidence.** A client MUST request a processing permission in its own detail, separate from any detail for ordinary access, even for the same source and purpose. The owner MUST select that detail by a distinct affirmative action, even when it is the only detail. The AS MUST NOT present it as selected by default. The owner MUST be able to approve every other detail while declining it, and the AS MUST NOT make approval of another detail depend on it. The AS MUST render each permission as a distinct, labeled term, not as part of the purpose. + +The owner approves or declines the detail as a whole. The AS MUST NOT issue its grant without its permissions, and MUST NOT add a permission to a detail that did not request it. Approval of ordinary access never confers a processing permission. The final approval artifact, review revision, retained consent evidence, issued grant, token result, and introspection result MUST carry the exact permission set. If the set changes after review, including by removal, the AS MUST reject approval and require a new review. + +#### AI training {#ai-training} + +`https://pdpp.dev/processing/ai_training` covers AI training. AI training means using data to fit or select the learned parameters or stored examples of a machine-learning model, generative or not, wherever the model runs, including on-device personalization and federated updates. It includes fine-tuning, distillation, reinforcement learning, and evaluation used to select a model, checkpoint, or hyperparameters. Fitting a model whose learned state is its stored examples, such as a nearest-neighbour classifier, is AI training. Those stored examples remain copies of PDPP data and are not learned parameters: the [erasure](#erasure) duty reaches them. Inference, retrieval, embedding generation with fixed parameters, building an index that a fixed model looks up, and measurement that never informs model selection are not AI training. Computing statistics, ranking by a fixed formula, and setting thresholds by hand are not AI training. For example, recommending concerts from a listening history with a fixed model is not AI training; fitting a per-owner recommendation model to that history is. This permission governs clients acting under grants. It does not limit what the owner does with data the owner exports. + +A PDPP input is [PDPP data](#data-concepts) used as an input. Its derivatives, and the model-output boundary, follow that definition. Removing identifiers from PDPP data, aggregating it, or declaring it anonymous does not end its status as a PDPP input for this rule. An exclusion from the erasure duty never permits AI training. + +A client MUST NOT use a PDPP input for AI training unless it has valid processing authority under the permission's defining profile for every contributing PDPP input. For data obtained through PDPP, a grant carrying `https://pdpp.dev/processing/ai_training` MUST cover the originating subject, source, stream, instance, fields, resources, and time constraint. The client MUST establish that coverage using authenticated issuer, subject, and client bindings; matching identifier strings alone is insufficient. For derived data, the coverage requirement applies recursively to every contributing PDPP input, subject to the model-output boundary above. Different grants MAY cover different contributing inputs. The acquisition grant need not be the training grant. If the client cannot establish coverage and valid authority for every contributing PDPP input, it MUST NOT use the input for AI training. Purpose codes, ordinary grants, and retention commitments never confer this authority. Every recipient or subprocessor to which a client passes PDPP inputs MUST observe the same restriction, and the client MUST impose it on them. An operator of an AS or RS MUST NOT use owner data that it holds in that role for AI training, except under a training grant issued to it as a client. This restriction is PDPP policy, independent of a recipient's lawful basis and of statutory rights. + +The PDPP AI Training Profile (forthcoming) defines how a training recipient maintains and exercises this authority. It defines the cessation bound for AI training, within the [registration test](#processing-permissions), and that bound applies wherever training runs. Until that profile is published and its registration as the defining profile is approved, the identifier is reserved. Every AS MUST treat it as unsupported: it MUST NOT advertise it and MUST reject a request that carries it. No grant can then carry it, so no client or operator holds AI training authority. + +Earlier drafts expressed AI training as the purpose code `https://pdpp.dev/purpose/ai_training`. A grant that carries that code confers no AI training authority. Training requires a fresh grant that carries this permission. + #### AI training consent {#ai-training-consent} -The AS MUST obtain explicit affirmative user consent before issuing any grant with `purpose_code` value `https://pdpp.dev/purpose/ai_training`. The owner MUST select an `ai_training` detail by a distinct affirmative action, and the AS MUST NOT present it as selected by default. When a request carries several details, the owner MUST be able to approve any other detail while declining the `ai_training` detail, and the AS MUST NOT make approval of another detail depend on it. The separate affirmative selection is required even when `ai_training` is the only requested detail. This rule adds to the final owner approval that every grant needs (Section 7). +A detail that carries the AI training permission MUST include a non-empty `purpose_description` that identifies the type of model, its functions, and the service or recipient it serves. The AS MUST reject such a detail without one, with `invalid_authorization_details` in the OAuth/RAR binding. The AS MUST label the detail as AI training on the approval surface. These rules add to [Consent and evidence](#processing-permissions) and to the final owner approval that every grant needs (Section 7). An AS MUST include `expires_at` in every grant carrying the AI training permission. The expiry MUST be later than `issued_at`. The AS MUST include that expiry in final owner review and bind it into the approval artifact and retained consent evidence. + +The approval surface for an AI training detail MUST state that learned parameters produced under valid processing authority may be kept and used for the reviewed purpose after the grant ends or the owner requests erasure. It MUST also state that stored examples remain subject to erasure and retention duties. It MUST NOT claim that keeping learned parameters is exempt from applicable law or from an order to restrict, retrain, or destroy the model. It MUST NOT claim that the model is anonymous, that withdrawal or erasure removes the owner's data from learned parameters, or that erasing the training data removes all personal information from the model. ### Stream selection parameters @@ -837,18 +938,21 @@ Per-stream, within the `streams` array. `name` and exactly one of a non-empty `f |-----------|------|--------|-------------| | `name` | string | Protocol-enforced | Stream name, or `*` for all streams (resolved at consent time against the retained SourceDeclaration). | | `necessity` | enum | Consent-flow control at issuance time | `optional` (default) or `required`. Optional streams are presented as user choices during consent. The AS MUST omit a declined optional stream from the grant and MUST retain a `required` stream or refuse issuance. If no stream remains, the AS MUST refuse issuance with `access_denied`. | -| `instance_ids` | string[] | Protocol-enforced | Optional opaque owner-instance handles for this stream. Handles are scoped to issuer, subject, `source.id`, and stream. Omission never means fan-in (reading across more than one connected instance of the same source). The AS resolves exactly one eligible handle or requires an explicit owner choice. | +| `instance_ids` | string[] | Protocol-enforced | Optional opaque owner-instance handles for this stream. A handle is scoped to issuer, subject, and client, is unique across sources, names one instance in every stream of its source, and is pairwise (see [Pairwise identifiers](#pairwise-identifiers)). Omission never means fan-in (reading across more than one connected instance of the same source). The AS resolves exactly one eligible handle or requires an explicit owner choice. | | `time_range.since` | RFC 3339 `full-date` or `date-time` | Protocol-enforced | Earliest data to include (inclusive, >=), evaluated against the stream's `consent_time_field`. Its type matches the field's format. | | `time_range.until` | RFC 3339 `full-date` or `date-time` | Protocol-enforced | Latest data to include (exclusive, <), evaluated against the stream's `consent_time_field`. Its type matches the field's format. A hard cap: applies to future resources as well as past ones. | | `view` | string | Protocol-enforced at issuance time | Named view defined by the authorization server. Mutually exclusive with `fields` in a request; both MUST NOT be present simultaneously. The OAuth/RAR binding maps a request with both to RFC 9396 `invalid_authorization_details`. | | `fields` | string[] | Protocol-enforced | Field allowlist. `["*"]` requests all permitted fields; `*` MUST then be the only element. Schema-required fields are always included regardless of this list. In v0.1, restricted to top-level field names only. Mutually exclusive with `view`. | -| `resources` | string[] | Protocol-enforced | Specific record IDs to authorize. Values are canonical key strings: minified JSON array for compound keys, plain string for simple keys. The AS validates arity and type against the retained declaration's `primary_key` at grant issuance. The RS filters by exact primary-key match. | +| `minimum` | object | Issuance condition | Optional `{ fields, time_range }` authorization minimum. See [Request resolution](#request-resolution). Not a data-availability or completeness guarantee. | +| `resources` | string[] | Protocol-enforced | Specific record IDs to authorize. Values are canonical key strings, as Compound key encoding in Section 4 defines: a plain string for a simple key. The AS validates arity and type against the retained declaration's `primary_key` at grant issuance. A failure of this check that depends on a declaration accepted only for the owner follows [Authorization privacy boundary](#authorization-privacy). The RS filters by exact primary-key match. In v0.1 a stream with `resources` covers exactly one instance. The AS MUST reject a request that has `resources` and more than one `instance_ids` entry for the stream; the OAuth/RAR binding returns RFC 9396 `invalid_authorization_details`. | **Note on `fields`:** At consent resolution, schema-required fields are always included in the resolved field set, regardless of the requested field list, because a record missing its schema-required fields is not a valid record of that stream; the per-stream consent floor is its required fields. -**Note on `time_range`:** `time_range` is only valid for streams that declare a `consent_time_field`. The authorization server MUST reject selection requests that specify `time_range` on a stream without that field. Its presence in the retained declaration is the authoritative signal that a stream is time-range-capable. +The resolved selection MUST contain at least one field for each retained stream. -**Time range bounds:** Each bound MUST have the type of the stream's `consent_time_field`: a `full-date` for a `date` field, and a `date-time` for a `date-time` field. A `time_range` MUST contain `since`, `until`, or both. The AS MUST reject a `time_range` with no bound, a bound of the wrong type, a bound that is not valid under [Time constraint semantics](#time-constraint-semantics), or a `since` that is not before `until`. The OAuth/RAR binding returns RFC 9396 `invalid_authorization_details`, as for other invalid details; `error_description` MAY name the failed check. The AS MUST NOT convert or round a bound. A client reads each field's format from the declaration and sends bounds of that type per stream. +**Note on `time_range`:** `time_range` is only valid for streams that declare a `consent_time_field`. The authorization server MUST reject selection requests that specify `time_range` on a stream without that field. A failure of this check that depends on a declaration accepted only for the owner follows [Authorization privacy boundary](#authorization-privacy). Its presence in the retained declaration is the authoritative signal that a stream is time-range-capable. + +**Time range bounds:** Each bound MUST have the type of the stream's `consent_time_field`: a `full-date` for a `date` field, and a `date-time` for a `date-time` field. A `time_range` MUST contain `since`, `until`, or both. The AS MUST reject a `time_range` with no bound, a bound of the wrong type, a bound that is not valid under [Time constraint semantics](#time-constraint-semantics), or a `since` that is not before `until`. The OAuth/RAR binding returns RFC 9396 `invalid_authorization_details`, as for other invalid details; `error_description` MAY name the failed check. A failure of this check that depends on a declaration accepted only for the owner follows [Authorization privacy boundary](#authorization-privacy). The AS MUST NOT convert or round a bound. A client reads each field's format from the declaration and sends bounds of that type per stream. **Note on wildcards:** `"streams": [{ "name": "*", "fields": ["*"] }]` requests all streams declared by the source. This is resolved against the retained snapshot and frozen as an explicit list in the grant. A stream that a later declaration adds is not part of the grant. If the wildcard request includes `instance_ids`, the AS applies the requested handles to every expanded stream and verifies that each handle is eligible for that stream. If it omits `instance_ids`, the usual exactly-one eligible instance rule applies to every expanded stream. @@ -858,6 +962,97 @@ A wildcard entry MUST be the only entry in `streams`. Otherwise stream names MUS **Defaults:** Each stream request, including each stream in a selection preset, MUST carry either `fields` or `view`. There is no implicit "all fields" default: a client that wants every permitted field sends `fields: ["*"]`, which the AS resolves against the retained snapshot. The marker is valid even when the stream declares `selection.fields: false`. The OAuth/RAR binding maps a stream request with neither `fields` nor `view` to RFC 9396 `invalid_authorization_details`. Omitting `necessity` means `optional`. Omitting `time_range` asks for no temporal constraint. Omitting `instance_ids` never asks for fan-in. The issued grant contains explicit non-empty `fields` and `instance_ids`. Clients SHOULD request only the data they need (see [Section 11, Data Minimization](#data-minimization)). +### Authorization privacy boundary {#authorization-privacy} + +For authorization requests, protected owner state includes the owner's connected sources and instances, their eligibility, private source-declaration acceptance, and owner-specific authorization conditions. A client identifier, identity hint, source identifier, or instance handle does not authenticate the owner. + +Before authenticating the owner, the AS MUST NOT make an externally observable authorization-processing result depend on protected owner state. For representative approval, the AS MUST verify the representative's authority before applying owner-dependent resolution or showing subject-specific information, as [Representative approval](#representative-approval) requires. + +The AS MAY validate request syntax, client identity, redirect and resource bindings, and owner-independent capabilities before owner authentication. The AS MUST preserve the errors required by the authorization binding for those failures. The AS MUST NOT redirect to an invalid redirect URI. + +The AS MUST defer a validation or resolution step when its result depends on protected owner state. The AS MUST perform that step within the authenticated owner's review interaction. This includes source acceptance held privately for the owner and the existence or eligibility of requested instance handles. The AS MUST NOT treat the absence of an eligible owner source or instance as malformed authorization details. + +For Core data-access details, request validity is determined from request structure and owner-independent capabilities. A syntactically valid selection that cannot be satisfied under a privately accepted declaration is an owner-dependent eligibility failure, not malformed authorization details. The AS MUST NOT return a client-visible declaration-dependent validation error for an unapproved source or stream. It MAY explain the failure within authenticated owner review. The `invalid_authorization_details` error remains for public invalidity, such as unknown members, invalid value grammar, and unsupported public capabilities. + +An AS that uses public source capabilities for early validation MUST determine those capabilities independently of the owner's private connections and eligibility. The AS MUST NOT derive a public capability response from protected owner state. The AS MUST NOT retrieve or accept a new declaration authority merely because an authorization request names it. + +The AS MUST treat an otherwise valid stream that has no eligible instance as unapproved. The AS MAY omit that stream only when it is optional. The AS MUST refuse the detail when a required stream cannot be retained. The AS MUST apply the existing required-stream and authorization-minimum rules before issuance. + +The AS MAY explain an owner-dependent failure to the authenticated owner within the protected review interaction. The AS MUST NOT disclose that explanation to the client without authorization for that disclosure. The AS MUST report an authorization refusal caused by source or instance ineligibility as `access_denied` in the OAuth binding. The AS MUST NOT distinguish that refusal from owner refusal by its client-visible response. This rule does not change `invalid_authorization_details` for malformed or unsupported details, or an error that this specification defines for a specific authorization-details type. A type-specific error remains subject to this boundary's no-inventory and observable-equivalence requirements. + +The AS MUST NOT treat owner authentication alone as authorization to disclose unapproved source or instance inventory to the client. The AS MUST limit a successful client result to the approved result defined in [Client-visible authorization result](#authorization-result). When a private validation failure requires owner interaction, the AS MUST NOT release an owner-dependent terminal result to the client before that interaction concludes. + +The AS MUST apply this boundary at every supported authorization entry point, including pushed authorization requests and noninteractive requests. Client authentication at a pushed authorization endpoint MUST NOT substitute for owner authentication. Acceptance of a pushed request MUST NOT assert that an owner can approve it. The AS MUST use the pushed-request binding's validation and response rules without returning an owner-interaction error at that endpoint. + +When a noninteractive request cannot proceed without owner authentication or review, the AS MUST use an error permitted by that binding for the missing interaction. The AS MUST NOT choose that error according to source or instance eligibility. A valid existing owner session MAY satisfy owner authentication. An identity hint MUST NOT satisfy it. + +For requests that differ only in protected owner state, the AS MUST use equivalent pre-authentication status, response structure, redirects, headers, and transaction-state behavior. The AS MUST prevent systematic differences in processing time from revealing that state. The AS MUST apply the same requirement to client-visible eligibility denials after authenticated review. Required request correlation values and unpredictable transaction values MAY differ when they do not reveal protected owner state. + +The AS MUST apply this boundary before it resolves owner-specific source or instance eligibility for final owner review (Section 7). A failed or stale eligibility check MUST remain within authenticated review until that interaction concludes. The AS MUST NOT expose the failed instance or the reason for its ineligibility in the client result. + +These requirements do not replace authentication-protocol requirements or the authorization binding's client, redirect, request-integrity, and abuse protections. + +### Request resolution {#request-resolution} + +The AS MUST expand presets, views, and wildcards against the retained declaration before applying owner choices. It MUST resolve the request into explicit grant constraints before final approval. It MUST preserve the client identity associated with the authorization request. + +#### Limits and owner choices + +Explicit requested instances, resources, and time bounds are upper limits. For fields, the upper limit is the field ceiling: the stream's expanded requested fields together with its schema-required fields. The AS MUST compute the ceiling before owner narrowing and minimum checks. The AS MUST NOT resolve outside those limits. Each stream names non-empty `fields`, a `view`, or `fields: ["*"]`; there is no implicit field selection. An omitted time range remains unbounded. Omitted instance handles retain the exactly-one-or-owner-choice rule. + +The schema-required fields here are the set that the AS freezes as the stream's `required_fields`; the AS MUST use that same set for the field ceiling, owner narrowing, and grant issuance. The AS MAY let the owner remove optional streams and narrow retained streams, but not below a stream's schema-required fields. The AS MUST NOT infer a client requirement from a schema-required property. It MUST retain each required stream or refuse the authorization. Narrowing a required stream does not itself constitute refusal if its explicit minimum remains satisfied. + +The AS MUST refuse issuance when the owner approves no streams. It MUST NOT add another source, stream, instance, field, or resource to compensate for a refused selection. A different proposal requires a new authorization request or an explicitly defined owner-selection binding. + +An AS MAY present bundles, contextual choices, or detailed controls. It MUST show the resolved disclosure and commitments before final approval. It MUST NOT present optional selections as compulsory. Core does not require a separate toggle for each selector. + +#### Explicit authorization minima + +The AS MUST recognize only `fields` and `time_range` inside `minimum`. It MUST reject empty minimum objects, unknown minimum members, duplicate field names, and fields outside the stream's field ceiling. A failure of this check that depends on a declaration accepted only for the owner follows [Authorization privacy boundary](#authorization-privacy). A supplied `minimum.fields` MUST be a non-empty array of declared top-level field names. + +For a retained stream, the AS MUST include every `minimum.fields` member in the resolved field selection. The AS MUST NOT treat a schema's `required` array as `minimum.fields`. For an optional stream, failure to satisfy its minimum permits omission of that whole stream, not a weaker retained stream. + +A supplied `minimum.time_range` MUST contain both `since` and `until`. Each bound MUST have the type of the stream's retained `consent_time_field` and MUST be valid under [Time constraint semantics](#time-constraint-semantics). `since` MUST be before `until`. The AS MUST NOT convert or round a bound. The AS MUST reject a minimum window outside the requested time window or on a stream without `consent_time_field`. A failure of this check that depends on a declaration accepted only for the owner follows [Authorization privacy boundary](#authorization-privacy). It MUST resolve a retained stream to a time window containing the entire minimum window. + +For these checks, an absent resolved lower bound means negative infinity and an absent upper bound means positive infinity. Comparisons follow [Time constraint semantics](#time-constraint-semantics): calendar order for `date` values and exact instant order for `date-time` values, never string order. Boundaries retain the inclusive-lower, exclusive-upper semantics of `time_range`. + +The AS MUST refuse issuance if an owner-approved required stream cannot meet its minimum. The OAuth binding MUST report this refusal as `access_denied`. Malformed or unsupported authorization details, judged under [Authorization privacy boundary](#authorization-privacy), instead produce `invalid_authorization_details`. Error descriptions MUST NOT reveal unapproved source, instance, record, or field existence. + +An authorization minimum describes permission, not the presence, freshness, completeness, or suitability of records. The AS MUST NOT require records to exist to satisfy an authorization minimum. A client MUST evaluate application sufficiency separately. Core does not define arbitrary predicates over records as issuance conditions. + +The AS MUST distinguish validation of a minimum's syntax and declared capability from satisfaction of that minimum by the owner's approved selection. The AS MUST apply [Authorization privacy boundary](#authorization-privacy) to each check. The AS MUST NOT test record presence, collection status, or data completeness to decide whether the minimum is satisfied. + +#### Recipient commitments and approval {#recipient-commitments} + +The AS MUST NOT interpret narrower access as recipient acceptance of a new purpose or retention obligation. It MUST resolve purpose and retention from the current request or applicable recipient-authorized standing terms before owner approval. It MUST retain the evidence identifying those terms and their version with the consent evidence. + +An AS MUST NOT treat a capability advertisement or owner-authored condition alone as recipient acceptance. When an owner condition is not covered by recipient authority, the AS MUST refuse issuance or obtain recipient acceptance before presenting the revised final approval. No particular acceptance transport is required by Core. + +Core represents these commitments through its existing purpose and retention fields. It does not define additional terms fields or a general agreement object. An AS MUST NOT claim that an unrepresented owner condition is a Core grant constraint. A companion that adds recipient obligations MUST define their result representation and acceptance evidence. + +The AS MUST NOT change `access_mode` merely as a consequence of narrowing data. The AS MAY choose grant expiry under its existing policy. Grant lifetime and record time scope remain separate. + +The AS MUST include the resolved purpose in final owner review. It MUST include that purpose in the grant. If retention is specified, the AS MUST include it in final owner review. It MUST include that retention in the grant. If grant expiry is specified, the AS MUST include it in final owner review. It MUST include that expiry in the grant. The AS MUST include any processing permissions in final owner review and in the grant, as [Processing permissions](#processing-permissions) defines. + +The AS MUST state during final owner review that ordinary access does not authorize the client to disclose PDPP data to an independent recipient. The AS MUST distinguish that restriction from processing by parties acting for the client under [Downstream holders](#downstream-holders). The AS MUST NOT describe this client duty as technical prevention of onward disclosure. + +Final owner review MUST also show what happens to held data after the grant ends, as [Held data after a grant ends](#held-data) defines: + +- for a grant without a processing permission, that the client may keep using the data it received for the approved purpose, unless the owner asks for deletion; +- for a grant that carries a processing permission, that the client may keep that data but has no ordinary surviving use of it. Continued processing is limited to already-issued processing authority within the defining profile's cessation bound and any earlier applicable deadline; +- the retention limit, or, when the grant has no `retention`, that there is no stated limit and the client may keep the data until it receives a deletion request; +- that the owner can ask for deletion at any time while the client may hold the data; +- that the client learns of a deletion request made at the AS only when it next obtains an answer from the AS. The client attempts one at least once a day while it runs, retrying hourly after a failed attempt and at least daily during a long outage ([Positive assessment and reconciliation](#reconciliation)); +- that an attempt is not an answer, and that there is no maximum delivery delay; +- that a client that is not running does not check, and learns of a deletion request only when it next runs and checks; +- that, if the AS stops answering for good, the client of a grant without a processing permission may keep and use the data for the approved purpose indefinitely when the grant states no retention limit; +- that, for a grant that carries a processing permission, the AS's silence lets the client keep the data but never extends processing authority or permits ordinary use; +- that a deletion covers all data the client received under the grant, its derivatives, and copies held by processors and in backups, subject to the exclusions and legal-retention exception in [Erasure](#erasure); +- that the client's stated retention limit, if any, bounds this, and that the owner can decline a grant that states none; +- that, if the client offers deletion, choosing it inside the client binds the client at once as an instruction, but is not instant physical deletion. + +The AS MUST complete required-stream and minimum checks before issuing a grant or a client token. It MUST NOT issue a temporary overbroad grant while choices are unresolved. Grant issuance does not authorize unrelated collection, billing, or source-side actions. + ### Selection presets Source declarations may define selection presets. A client can reference a preset instead of constructing explicit stream selections: @@ -876,7 +1071,7 @@ The authorization server expands the preset from the retained snapshot into expl Each selection preset MUST NOT contain the same stream name more than once. Duplicate stream names make the declaration invalid. They are not deferred to grant issuance. -Every field in the issued grant is derived from either the selection request, client registration, or authorization server policy. The grant never contains values whose source is ambiguous. +Every field in the issued grant is derived from the selection request, explicit owner resolution, client registration, or authorization server policy. Recipient commitments additionally require the authority described in [Request resolution](#request-resolution). The grant never contains values whose source is ambiguous. --- @@ -895,7 +1090,7 @@ A grant covers one subject, one source, and one purpose. This is a granularity r "version": "0.1.0", "grant_id": "grt_8f72a1b3", "issued_at": "2026-04-06T15:00:00Z", - "subject": { "id": "user_abc123" }, + "subject": { "id": "sub_Jq4tN8wR" }, "client": { "client_id": "music_recommendations" }, "source": { "kind": "connector", "id": "https://registry.pdpp.dev/connectors/spotify" }, "source_declaration": { "version": "2026-08-11" }, @@ -905,7 +1100,7 @@ A grant covers one subject, one source, and one purpose. This is a granularity r "streams": [ { "name": "top_artists", - "instance_ids": ["spotify-account-a"], + "instance_ids": ["inst_K4wq8Rn2"], "fields": ["id", "name", "genres", "popularity", "source_updated_at"], "time_constraint": { "field": "source_updated_at", @@ -915,7 +1110,7 @@ A grant covers one subject, one source, and one purpose. This is a granularity r } ], "retention": { - "max_duration": "P1Y", + "max_duration": "P365D", "on_expiry": "delete" }, "expires_at": "2027-04-06T00:00:00Z" @@ -931,33 +1126,60 @@ A grant covers one subject, one source, and one purpose. This is a granularity r | `version` | string | yes | Protocol metadata | Tracks the version of this specification's grant schema (not a URL; there is no external schema document to resolve). This contract requires exactly `0.1.0`. | | `grant_id` | string | yes | Protocol metadata | Unique identifier. | | `issued_at` | ISO 8601 | yes | Protocol metadata | When the grant was issued. | -| `subject` | object | yes | Identity binding | Exactly `{ id }`. The `subject.id` is an opaque string, unique within the issuing AS's namespace. No format constraint is imposed. | +| `subject` | object | yes | Identity binding | Exactly `{ id }`. The `subject.id` is an opaque string, unique within the issuing AS's namespace. It is the subject's pairwise identifier for the grant's client (see [Pairwise identifiers](#pairwise-identifiers)). No format constraint is imposed. | | `client` | object | yes | Identity binding | Exactly `{ client_id }` or `{ client_id, client_display }`. `client_display`, when retained, contains requester metadata presented during consent. Inline values remain unverified unless separately validated; their presence in the grant does not attest to verification. A displayed `policy_uri` or `tos_uri` is retained as its exact URI target. | | `source` | object | yes | Protocol-enforced | Exact `{ kind, id }` retained from the accepted SourceDeclaration. `id` is authorization identity; `kind` is provenance metadata. | | `source_declaration` | object | yes | Protocol evidence | `{ version }` records the opaque revision of the exact declaration snapshot used for consent and issuance. It is evidence metadata, not a live lookup authority. | | `purpose_code` | URI | yes | Structured policy declaration | Machine-readable purpose (see Appendix A). | | `purpose_description` | string | no | Structured policy declaration | Human-readable purpose. | | `access_mode` | enum | yes | Protocol-enforced | `single_use` or `continuous`. | +| `processing_permissions` | string[] | no | Protocol-enforced | The exact set of processing permissions the owner approved, as unique absolute URIs. Present only when non-empty; absent means none. Confers no read access. See [Processing permissions](#processing-permissions). | | `streams` | StreamGrant[] | yes | Protocol-enforced | Granted streams. Always expanded; no wildcards. See StreamGrant fields table below. | | `selection_preset` | string | no | Informational | Which SourceDeclaration preset was selected. The resolved streams and fields remain authoritative. | | `retention` | object | no | Structured policy declaration | Policy commitment by the data recipient (see below). | -| `expires_at` | ISO 8601 | no | Protocol-enforced | Grant expiry. Absent means no expiry. | -| `grantors` | object[] | no | Identity binding | Present only when representatives approved on the subject's behalf. When present, this is a non-empty list of distinct approving representatives. Absence means the subject approved. Core v0.1 does not encode joint approval by the subject and a representative. Each entry is exactly `{ id, capacity }`. `id` is an opaque identifier of the approving person, unique within the issuing AS's namespace. For grants returned to clients, the AS MUST use an identifier specific to that client. `capacity` is an absolute URI that names the basis on which that person approved, such as a parental or legal-representative capacity defined by a profile or deployment. See [Representative approval](#representative-approval). | -| `extensions` | object | no | Profile data | Optional object keyed by absolute profile URI. Core preserves or ignores an unknown extension value and does not parse it. An extension cannot widen what the grant authorizes or weaken Core semantics. | +| `expires_at` | ISO 8601 | yes for AI training; otherwise no | Protocol-enforced | Grant expiry and the latest possible end of processing authority. Required when `processing_permissions` includes `https://pdpp.dev/processing/ai_training`. Otherwise, absence means no expiry. | +| `grantors` | object[] | no | Identity binding | Present only when representatives approved on the subject's behalf. When present, this is a non-empty list of distinct approving representatives. Absence means the subject approved. Core v0.1 does not encode joint approval by the subject and a representative. Each entry is exactly `{ id, capacity }`. `id` is an opaque identifier of the approving person, unique within the issuing AS's namespace. Like `subject.id`, it is pairwise for the grant's client (see [Pairwise identifiers](#pairwise-identifiers)). `capacity` is an absolute URI that names the basis on which that person approved, such as a parental or legal-representative capacity defined by a profile or deployment. See [Representative approval](#representative-approval). | +| `extensions` | object | no | Profile data | Optional object keyed by absolute profile URI. Core preserves or ignores an unknown extension value and does not parse it. An extension cannot widen what the grant authorizes or weaken Core semantics. A processing permission is carried only in `processing_permissions`, never in `extensions`. | ### StreamGrant fields | Field | Type | Required | Status | Description | |-------|------|----------|--------|-------------| | `name` | string | yes | Protocol-enforced | Unique stream name within the grant. Always concrete; no wildcards in issued grants. | -| `instance_ids` | string[] | yes | Protocol-enforced | Unique non-empty opaque instance handles scoped to issuer, subject, source ID, and this stream. Multiple handles authorize fan-in only when explicitly listed. Example: two connected Gmail accounts are two instances of the same source kind, each with its own handle. | +| `instance_ids` | string[] | yes | Protocol-enforced | Unique non-empty opaque instance handles. A handle is scoped to issuer, subject, and client, is unique across sources, names the same instance in every stream of its source, and is pairwise (see [Pairwise identifiers](#pairwise-identifiers)). Authorization stays per stream: the handles this row lists authorize this stream only. Multiple handles authorize fan-in only when explicitly listed. Example: two connected Gmail accounts are two instances of the same source kind, each with its own handle. | | `fields` | string[] | yes | Protocol-enforced | Unique non-empty resolved field allowlist, authoritative for RS enforcement. Top-level field names only. | | `time_constraint` | object | no | Protocol-enforced | Frozen `{ field, type, since?, until? }` resolved from the retained declaration. `field` and `type` are required and at least one bound is present. `type` is `date` or `date-time`; the AS sets it at issuance from the field's format in the retained declaration. Each bound has that type. `since` is inclusive; `until` is exclusive. | -| `resources` | string[] | no | Protocol-enforced | Authorized record IDs in canonical key string encoding. Absent means all records. | +| `resources` | string[] | no | Protocol-enforced | Authorized record IDs in canonical key string encoding. Present only when `instance_ids` has exactly one handle. Absent means all records. | Request-only conveniences such as wildcard names, the `*` field marker, `view`, and omitted instance handles are fully resolved before final owner review and issuance. They are not continuing authority in the grant. Selection provenance may be retained at grant level through `selection_preset`; the concrete stream rows remain authoritative. -Before the final approval surface is shown, the AS MUST resolve omitted `instance_ids` to exact eligible instance handles or require an explicit owner choice. The final approval artifact MUST include the exact resolved `instance_ids`, stream names, fields, resources, temporal field, `since` stated as inclusive, `until` stated as exclusive, purpose, retention, client identity, and grant expiry. If `client_claims` are rendered during final review, the final approval artifact and review revision MUST also bind the normalized exact claims with client attribution. Retained consent evidence MUST preserve that binding. The approval mutation MUST bind to an immutable review revision or digest over the authorization decision fields. `client_claims` MUST remain outside the resolved grant and RS enforcement. If instance eligibility or the reviewed revision becomes stale before approval, the AS MUST reject approval and require a new review. +Before the final approval surface is shown, the AS MUST resolve omitted `instance_ids` to exact eligible instance handles or require an explicit owner choice. For a stream with `resources`, that choice is exactly one instance. The final approval artifact MUST include the exact resolved `instance_ids`, stream names, fields, resources, temporal field, `since` stated as inclusive, `until` stated as exclusive, purpose, retention, processing permissions, client identity, and grant expiry. If `client_claims` are rendered during final review, the final approval artifact and review revision MUST also bind the normalized exact claims with client attribution. Retained consent evidence MUST preserve that binding. The approval mutation MUST bind to an immutable review revision or digest over the authorization decision fields. `client_claims` MUST remain outside the resolved grant and RS enforcement. If instance eligibility or the reviewed revision becomes stale before approval, the AS MUST reject approval and require a new review. + +### Client-visible authorization result {#authorization-result} + +The AS MUST return one `authorization_details` element per covered grant in every successful OAuth token response that issues a client access token, including refresh responses. Each element MUST contain `type` equal to `https://pdpp.dev/data-access` and `grant` containing the complete immutable grant defined by this section. The AS MUST NOT substitute the original selection request or a lossy summary. A [lifecycle recovery](#lifecycle-recovery) token covers no grant for reads; its token response returns the approved recovery element instead. A token response that returns a grant is also a [positive assessment](#reconciliation) for that grant. + +The result MUST include source provenance, declaration revision, resolved streams, instance handles, fields, the frozen required-field subsets, resource and time constraints, recipient commitments, access mode, and processing permissions and grant expiry when present. The full grant includes the resolved client identity and reviewed client display defined above. Omitted optional streams are not grants and MUST NOT appear as authorized in the result. + +The client MUST inspect the result before requesting record disclosure. It MUST NOT infer authorization from its original request, an MCP tool listing, or a token's syntax. A client unable to obtain or interpret the result MUST NOT request disclosure. An AS MAY omit only values that the grant definition itself makes optional. + +For a credential that a companion binding defines to cover several grants, the AS MUST return every covered grant as a separate element. It MUST NOT merge fields, instances, or resources across grants. A binding supporting such tokens MUST preserve each grant's source and client association during enforcement. + +The AS MUST return the same resolved grant facts to the client and to an authenticated RS, apart from token-specific active-state and expiry fields. Receiving this result does not grant the client access to the RS-authenticated introspection endpoint. The AS MUST protect result delivery as part of the authenticated OAuth exchange. + +Owner approval covers disclosure of the result's identifiers and metadata to the client. The AS MUST NOT include inventory for unapproved sources or instances. A successful token response consumes a `single_use` grant as defined below even if the client subsequently declines to read. + +### Pairwise identifiers {#pairwise-identifiers} + +Every identifier for the subject, a grantor, or an instance that a client receives is pairwise, as [OpenID Connect Core 1.0 Section 8.1](https://openid.net/specs/openid-connect-core-1_0.html#PairwiseAlg) defines for `sub`. This covers `subject.id`, each `grantors[].id`, and each instance handle, in a grant, a record, or any other response to the client. The AS MUST give different clients different identifiers for the same subject, grantor, or instance. It MUST give one client the same identifier for that subject, grantor, or instance in every grant and response, and MUST NOT reassign the identifier to another subject, grantor, or instance. The identifier MUST NOT be reversible by clients: a client cannot derive the internal identifier, or another client's identifier, from it. A value such as `clientA:user123`, which joins a client name to an internal identifier, does not meet this rule. Clients that share an OpenID Connect sector identifier count as one client for these rules. + +These rules also cover the `sub` claim of an OpenID Connect ID Token that the AS issues to the client. That claim identifies the person who authenticated. When a representative listed in `grantors` authenticates, `sub` is that representative's pairwise identifier, the same value as their `grantors[].id`, and not the subject's. + +A per-client decentralized identifier (DID), such as a pairwise or peer DID, meets this rule and MAY serve as the pairwise identifier. The one exception is owner choice. The AS MAY use a globally resolvable identifier, such as a DID, as a client's `subject.id` only when the owner explicitly chooses to disclose it to that client. The final approval artifact MUST bind the exact identifier and the receiving client, and retained consent evidence MUST preserve that binding. Core defines no other use of such an identifier (Section 12). The choice is fixed for that subject and client before the client's first grant. The AS MUST NOT change a client's `subject.id` between the pairwise value and the chosen identifier in a later grant. + +The AS and RS MAY also keep an internal subject identifier, which passes only between them. In a separated deployment, the AS returns it to the RS as the introspection `subject_id`, and the RS uses it to find the subject's data (Section 8). The RS MUST NOT disclose it to a client. An introspection result or grant that the AS returns to a client carries only that client's pairwise identifiers. The RS maps a client's handles to stored instances only through `pdpp_instance_bindings` (Section 8), which the AS never returns to a client. + +These rules stop clients from correlating one owner through the identifiers above. They do not make disclosures unlinkable. Record keys, `blob_id` values, content hashes such as `sha256`, timestamps, and other record content can still link one owner's disclosures across clients. ### Representative approval {#representative-approval} @@ -1003,9 +1225,22 @@ The current persisted-authorization-state reader MUST reject any persisted autho | Mode | Behavior | |------|----------| -| `single_use` | The grant permits one fixed read window. The window opens at the first client access token issuance for the grant and ends at that token's expiry. The AS marks the grant consumed atomically with that issuance. The first token MUST have a finite expiration, set by AS local policy and, when the grant has `expires_at`, no later than `expires_at`. That expiration SHOULD be short. The window does not limit the client to one request: the client MAY use the token for repeated reads, retries, and pagination until the window ends or the grant is revoked. A later access token in the same refresh-token family MAY carry the grant, but only inside the window. A binding that allows this MUST let the resource server enforce the window end, including under a cached introspection result and for a signed blob URL. After the window ends, no token carries the grant, and introspection MUST NOT report the grant active. After first issuance, the AS MUST reject issuance against the consumed grant, except a successor access token from the same refresh-token family issued before the window ends. A `single_use` grant never opens a second window. Failure to complete retrieval inside the window does not un-consume the grant. | +| `single_use` | The grant permits one fixed read window. The window opens at the first client access token issuance for the grant and ends at that token's expiry. The AS marks the grant consumed atomically with that issuance. The first token MUST have a finite expiration, set by AS local policy and, when the grant has `expires_at`, no later than `expires_at`. That expiration SHOULD be short. The window does not limit the client to one request: the client MAY use the token for repeated reads, retries, and pagination until the window ends or the grant is revoked. A later access token in the same refresh-token family MAY carry the grant, but only inside the window. A binding that allows this MUST let the resource server enforce the window end, including under a cached introspection result and for a signed blob URL. After the window ends, no access token carries the grant, and introspection MUST NOT report the grant active for reads. The end of the window ends read access only; it does not by itself end processing authority ([Read access and processing authority](#processing-authority)). After first issuance, the AS MUST reject further access-token issuance against the consumed grant, except a successor access token from the same refresh-token family issued before the window ends. This restriction does not prohibit issuance or renewal of processing credentials under the permission's defining profile. A `single_use` grant never opens a second window. Failure to complete retrieval inside the window does not un-consume the grant. | | `continuous` | The grant is fulfilled repeatedly. The client may query the resource server incrementally over time. Active until expiry or revocation. | +### Read access and processing authority {#processing-authority} + +A grant that carries a processing permission confers two distinct kinds of authority. Read access lets a client obtain records through tokens that the RS enforces. Processing authority lets a client perform the permitted operation on PDPP inputs it holds, as the permission's defining profile governs. Token activity, introspection `active`, and the `single_use` read window describe read access only. + +- The end of a `single_use` read window, or the expiry of an access token, does not by itself end processing authority. +- A processing credential never confers read access. It never makes a token active or reopens a read window. +- When a grant is revoked, read access ends and the AS MUST issue no further processing authority under it. Authority already issued ends within the cessation bound that the defining profile sets. Revocation here includes owner revocation, client-initiated revocation that ends the grant (Section 10), revocation by the AS for a security reason, and a companion operation that ends the grant. +- If a grant has `expires_at`, processing authority ends no later than that time. The AS MUST NOT issue processing authority that outlasts it. +- Replay detection on a refresh-token family (Section 10) invalidates that family's tokens, and with them read access through those tokens. It does not by itself end processing authority. +- Ending one grant does not end processing authority under another grant. An erasure instruction is the exception: from its effective time, the AS MUST issue no further processing authority, under any grant of the same client, that permits use of the data the instruction covers ([Erasure](#erasure)). Authority already issued for that data ends within the defining profile's cessation bound, measured from that effective time. Authority MUST NOT outlast a known future effective time of an advance instruction. + +The defining profile defines how processing state is represented, the credentials that carry processing authority, and how processing ceases. The [grant lifecycle operation](#grant-lifecycle) reports grant and erasure state, not processing state. + ### Time constraint semantics {#time-constraint-semantics} The selection request's `time_range` is resolved against the retained stream `consent_time_field` into the grant's `time_constraint`. The grant freezes that field, its type, and the bounds. The filter is: @@ -1033,29 +1268,330 @@ For `continuous` grants without `time_constraint.until`, future records in a gra Grants freeze stream names, instance handles, fields, and any time constraint at consent time. Within that resolved scope, future records are included for `continuous` grants. Future stream types or fields are not included; they require a new grant. -### Grant narrowing +### Grant narrowing {#grant-narrowing} Grant narrowing (reducing the scope of an existing grant) is not supported in v0.1. Scope reduction is achieved via revoke-and-reissue: the existing grant is revoked (see [Revocation](#revocation)) and the user issues a new, narrower grant. Authorization server UIs SHOULD model this flow as revocation followed by a new grant request. -### Records from revoked grants +The revocation in this flow is an owner withdrawal and carries a disposition ([Ending paths](#ending-paths)). On that surface the AS MUST state that `delete` makes the client delete its copy from the old grant, subject to the exclusions in [Erasure](#erasure). Only what the new grant covers can then return, by being read again under the new grant. It MUST state that `keep` leaves the client's existing copy usable under the old grant's surviving-use terms, including data that the new grant does not cover. -Revocation stops future access only. Records already delivered to the client before revocation are governed by the grant's `retention` policy and applicable legal obligations. PDPP does not retroactively reach into client-side data stores. +### Held data after a grant ends {#held-data} -### Retention +The rules from here to [Lifecycle durability](#lifecycle-durability) govern the [held data](#data-concepts) of a grant, while the grant is active and after it ends. They bind the client and every party acting for it ([Downstream holders](#downstream-holders)), and the AS duties they depend on. PDPP cannot technically enforce the client's duties. A conforming client's records make a breach attributable, not impossible. + +**Learned-parameter exception.** Learned parameters produced under valid processing authority before that authority ended may be retained and used within the purpose the owner reviewed. The contribution of PDPP inputs to those parameters does not, by itself, subject the parameters to the input grants' reconciliation, surviving-use prohibition, retention-disposal, or erasure duties. This exception does not cover stored source examples, training-data copies, retrieval stores, or other retained inputs and derivatives. It does not authorize further training on PDPP inputs without the covering permission and valid processing authority. It is a term of PDPP authority that the owner approves. It does not limit any legal duty or order to restrict, retrain, or destroy a model. Model outputs follow the boundary in [Data concepts](#data-concepts). This exception does not authorize disclosure of PDPP data to an independent recipient. Such disclosure remains subject to [Independent-recipient disclosure](#independent-recipient-disclosure). + +**Use.** Use of held data means serving, displaying, querying, computing with, training on, or disclosing it, including through queued or in-flight work. Keeping data, deleting it, and processing that the [legal-retention exception](#erasure) permits are not use. + +**Surviving-use terms.** When a grant ends, read access ends (Section 10). Already-issued processing authority ends within the defining profile's cessation bound ([Read access and processing authority](#processing-authority)). An ending by itself creates no erasure instruction. Unless an erasure instruction applies, the client MAY keep the grant's held data and MAY use it only within the grant's surviving-use terms: + +- For a grant without a processing permission, the surviving use is use for the grant's approved purpose, within its `retention`, excluding independent-recipient disclosure ([Independent-recipient disclosure](#independent-recipient-disclosure)). +- For a grant that carries a processing permission, there is no ordinary surviving use. The client MAY keep data held under that grant alone. Already-issued processing authority remains usable only to the extent, and until the cessation deadline, permitted by its defining profile; the client MUST NOT otherwise use the data. Keeping it never makes it usable for another purpose. + +Use of held data for any other purpose needs a new grant. The [time limits](#held-data-limits) and the [positive-assessment rule](#reconciliation) apply whether or not the grant has ended. + +#### Held-data time limits {#held-data-limits} + +Core fixes four time limits for held data. The rest of this specification refers to them by name. + +| Limit | Value | Meaning | +|---|---|---| +| Reconciliation interval | 24 hours | Longest interval between a client's lifecycle query attempts for a grant while the client runs and it, or a party acting for it, holds held data of that grant. | +| Retry interval | 1 hour | Longest interval between the starts of successive attempts while the client runs after a failed or unanswered lifecycle query, subject to the retry and resume rules in [Positive assessment and reconciliation](#reconciliation). A `Retry-After` from the AS, or sustained transport failure, can lengthen it, never beyond the reconciliation interval. | +| Stop-use bound | 48 hours | Longest time from the effective time of an erasure instruction to the end of use, for a client that learns of the instruction before that time has passed. | +| Deletion bound | 30 days | Longest time from a client's first authenticated receipt of an erasure instruction to the end of deletion. | + +Hours and days in this table are elapsed time; a day is 24 hours. ASs and clients MUST enforce these limits using conservative time bounds that include clock uncertainty. A client MUST count time spent suspended or powered off. Clock rollback, restart, restored state, or an uncertain mapping between an AS timestamp and the client's clock MUST NOT extend a deadline. If the client cannot establish that a use deadline has not passed, it MUST NOT use the data until it establishes that. Before further use after an interruption, it MUST establish whether disposal is overdue and complete any overdue disposal. If it cannot establish that a disposal deadline remains in the future, it MUST treat disposal as due. The legal-retention exception still applies. Core does not prescribe a particular time service or clock implementation. + +#### Ending paths {#ending-paths} + +A grant ends by revocation or by expiry. A disposition is the owner's choice for one ended grant: `keep` or `delete`. A `delete` disposition records an [erasure instruction](#erasure). A `keep` disposition records that the surviving-use terms apply. Each path below has a fixed effect on held data. + +| Path | Effect on held data | +|---|---| +| Owner withdrawal at the AS, including disconnecting a whole client or a package | The AS MUST obtain an explicit disposition for each grant in the action's scope. A whole-client or package action includes already-ended and consumed grants whose held data may remain, as well as active grants and separate processing-permission grants within that scope. One choice MAY apply to all. Before the final step, the AS MUST list the complete affected set and distinguish grants it will end from ended grants whose held-data disposition it will record. | +| Owner withdrawal of one package child | The disposition covers that child only. The other children and the shared credential stay active ([extended access profile](spec-access-extension)). Under `delete`, a derivative that mixes that child's data with other data is covered as [Erasure](#erasure) defines. | +| Narrowing by revoke-and-reissue | An owner withdrawal that carries a disposition, as [Grant narrowing](#grant-narrowing) defines. | +| Client-initiated revocation at the owner's direction | The owner's choice binds the client from the moment the owner makes it in the client, whether or not the AS records it ([Disconnect in the client](#client-disconnect)). The client SHOULD convey the choice as `pdpp_disposition` on the revocation request (Section 10). | +| Client-initiated token revocation without a disposition | Revocation ends the token, and ends grants as Section 10 defines. It creates no erasure instruction. | +| Expiry | Read access and processing authority end at `expires_at`. Expiry creates no erasure instruction, but an erasure the owner elected in advance takes effect. Held data follows the surviving-use terms. | +| Security revocation by the AS | The AS ends a grant that the owner did not ask to end, for example because the client is compromised or delisted. This creates no erasure instruction. The AS MUST show the owner that the grant ended and why, and MUST offer the disposition until the owner chooses. | +| Refresh-token replay | A credential event, not a grant ending (Section 10). It creates no erasure instruction. | +| AS decommission | Before an AS stops answering lifecycle queries for good, it MUST offer the owner a disposition for every grant whose held data may remain. It MUST show each disposition as offered, recorded, sent, or receipt reported. It MUST warn the owner about each `delete` that no client has received yet: once the AS stops answering, the client cannot learn of it. | + +Any interface through which the owner ends a grant, including a programmatic or MCP interface, MUST require an explicit disposition for every grant in the action's scope. The AS MUST reject a request that lacks one and MUST NOT apply a default. On an interactive surface, the AS MUST present `keep` and `delete` before the final step, with neither preselected. For `keep`, the AS MUST show the surviving-use terms and the retention limit. For `delete`, it MUST show the statements that [Erasure](#erasure) requires. + +The AS MAY let the owner elect deletion before a grant ends. The AS MUST durably record the election as an erasure instruction whose effective time is the end of the grant. Before that time, the election alone MUST NOT revoke the grant, prohibit use, or prohibit issuance of processing authority. An immediate erasure request for the same grant MUST end the grant and make that instruction effective at that ending. It MUST retain the instruction identifier and original acceptance record. While held data of an ended grant may remain ([Lifecycle durability](#lifecycle-durability)), the AS MUST let the owner request its erasure. Erasure requested after a `keep` disposition creates an instruction if none exists. An effective instruction MUST NOT be cancelled or postponed. + +#### Disconnect in the client {#client-disconnect} + +A client that offers the owner a way to disconnect it, or to end its access, MUST state in that flow what happens to held data. It MUST let the owner choose `keep` or `delete`, with neither preselected. When the owner chooses `delete`, that choice is an erasure instruction for the client, effective at once. It counts as the client's first authenticated receipt of the instruction ([Erasure](#erasure)). The client SHOULD convey it to the AS, with the time of the choice as `reported_at`: as `pdpp_disposition` on the revocation request (Section 10), or through the [grant lifecycle operation](#grant-lifecycle) when no revocation is involved. + +#### Positive assessment and reconciliation {#reconciliation} + +**Positive assessment.** A positive assessment is an authenticated AS answer that permits the client to keep a grant's held data and to use it within the grant's surviving-use terms. A positive assessment confirms custody eligibility; it authorizes no use outside the applicable surviving-use terms and confers no processing authority. Exactly two answers are positive assessments: + +- a lifecycle answer whose `held_data` is `permitted` ([Grant lifecycle operation](#grant-lifecycle)); +- a successful token response that returns the grant in its [authorization result](#authorization-result). + +Record delivery by the RS, an introspection result, a read error, and a package read status are not assessments. + +The AS MUST NOT return a positive assessment for a grant to which an erasure instruction applies. Otherwise a lifecycle answer is positive whatever the grant's read state: active, read window closed, expired, or revoked. The AS MUST compute every positive assessment from state ordered after every terminal event it has acknowledged ([Lifecycle durability](#lifecycle-durability)). + +A lifecycle answer carries the time of the assessment in `assessed_at`. The client MUST associate each assessment with its original request. A delivery, a cache hit, a replay, or a retry that returns an earlier assessment is not a new assessment. + +**First use.** Before first use of a grant's held data, the client MUST hold a positive assessment for that grant. Silence from the AS is not an erasure instruction. A client that cannot reach the AS keeps its held data and MAY continue to use it as the grant permits. + +**Reconciliation.** While the client runs and it, or a party acting for it, holds any held data of a grant, the client MUST attempt a lifecycle query for that grant at least once per reconciliation interval. The first attempt is due one reconciliation interval after the client first acquires data under the grant. A successful token response that returns the grant counts as a query. Transforming, rereading, relabeling, or moving data never restarts the interval. No attempt is due while neither the client nor a party acting for it holds data of the grant. If it later holds such data again, the duty resumes, and once a reconciliation interval has passed it MUST start a lifecycle query before further use. + +The client MUST also start a query before further use of held data in two cases: + +- a read or refresh fails in a way that shows the grant may have ended, such as HTTP 401 with Bearer error `invalid_token`, `grant_revoked`, `grant_expired`, `package_child_inactive`, or `invalid_grant` from the token endpoint; +- the client resumes from suspension or power-off after an attempt fell due. + +These duties require an attempt, not a successful answer. A failed or unanswered query does not stop use that the grant's terms still permit. Every known erasure, retention, and processing deadline still binds. + +**Retries.** An attempt succeeds when it returns a lifecycle answer for the grant. A successful token response that counts as a query also ends retries. A transport error, an HTTP 401, 429, or 5xx response, or a per-grant error is a failure. While the client runs, unless an attempt succeeds, it MUST start its next attempt within the retry interval of the preceding attempt's start, even if that attempt remains unanswered. This duty applies while the client runs, until an attempt succeeds or it holds no held data of the grant. On resume after an attempt fell due, it MUST start a lifecycle query before further use. Suspension and power-off do not extend use or disposal deadlines. The client SHOULD space retries by exponential backoff with jitter, capped at the retry interval. After every attempt for at least one reconciliation interval has failed at the transport level, the client MAY widen the interval between attempt starts up to the reconciliation interval until an attempt gets an HTTP response. When the AS sends `Retry-After`, the client MAY wait that long instead of the retry interval. The reconciliation interval takes precedence over `Retry-After`: the client MUST still attempt a query once per reconciliation interval. Neither an unanswered attempt nor a failed attempt extends a use or disposal deadline. + +### Erasure {#erasure} + +**Instruction.** An erasure instruction covers one grant. The AS records one when the owner chooses `delete` ([Ending paths](#ending-paths)), when the owner requests erasure later, or when a client conveys an owner's `delete` with current client authentication ([Grant lifecycle operation](#grant-lifecycle)). The AS MUST record each instruction durably before acknowledging it, with an identifier, the grant, and its acceptance time ([Lifecycle durability](#lifecycle-durability)). Its effective time is its acceptance time, or the end of the grant for an election made in advance. An instruction applies from its effective time. An instruction that takes effect while its grant is active also revokes the grant. An owner's `delete` choice made in the client is an erasure instruction for that client from that moment ([Disconnect in the client](#client-disconnect)). + +**Terminal.** An accepted erasure instruction is terminal for the data it covers. A later `keep` disposition, a retry, expiry, a new grant, or reapproval MUST NOT cancel it. At most one erasure instruction applies to a grant; a repeated request returns the existing instruction. Redelivery of an instruction never restarts a clock. + +**Scope.** An erasure instruction covers all held data of its grant, which includes: + +- data the client received under the grant, including deliveries made after the effective time within the read-propagation bound (Section 10); +- every derivative of that data, including derivatives produced before use stopped, embeddings, indexes, caches, labels, and training-data copies; +- the stored examples of a model whose learned state is its stored examples ([AI training](#ai-training)); +- copies held by any party acting for the client, and backup copies. + +A derivative that mixes covered data with other data MUST be deleted, or regenerated without the covered data. Regeneration MUST remove the old derivative. + +The instruction does not cover: + +- learned parameters of a model produced under valid processing authority before that authority ended; +- data that, before the effective time, the client rendered non-identifiable under a test it states in its records. Non-identifiable means that neither the client nor any other party can link the data to the owner by means reasonably likely to be used. Pseudonymized data, and data that keeps a per-owner key, hash, or identifier, is not non-identifiable; +- a copy the client acquired independently under another grant whose surviving-use terms still let the client keep it, where the client's acquisition records show that acquisition. + +Relabeling or deduplicating one acquisition does not create a second one. An exclusion from erasure never permits AI training ([AI training](#ai-training)). An erasure instruction always requires deletion: `retention.on_expiry: anonymize` does not satisfy it. + +**Stop use.** On learning of an erasure instruction, the client MUST stop use of the covered data as soon as practicable, including queued and in-flight work. It MUST stop no later than the stop-use bound after the effective time. If it learns of the instruction after that deadline, it MUST stop at once. + +**Delete.** The client MUST delete the covered data no later than the earlier of these times: + +- its first authenticated receipt of the instruction plus the deletion bound; +- each record's [retention ceiling](#grant-retention). + +The first authenticated receipt is the first lifecycle answer that carries the instruction, or the owner's `delete` choice made in the client. The client MUST record when it occurred. A later delivery, acknowledgement, forwarding, or AS record MUST NOT restart the deadline. + +**Backups.** Destroying the keys that protect a backup meets a deadline only if it makes the covered data irrecoverable. A backup rotation that ends after the deadline does not meet it. A client that keeps immutable backups for longer than the deletion bound cannot meet that bound by rotation alone. A restore MUST replay deletion state before any restored data becomes usable. + +**Overdue disposal.** A client that misses a deletion deadline, for example while powered off, MUST complete the deletion before any further use of data of that grant. It MUST record the missed deadline and MUST NOT report the deletion as completed on time. + +**Legal retention.** Where law requires the client to keep some covered data, the client MAY keep that data for that obligation only. It MUST NOT process that data except as the obligation requires. This exception covers legally required retention only. It gives no general right to continue clinical or other use after the owner chooses `delete`. Such use is outside v0.1, unless the client holds an independently acquired copy. The client MUST record the scope of the retained data, the legal basis, and the end of the obligation. It records the end as a date, as an event or condition, or as unknown, and MUST NOT record an invented date. It MUST report the exception, with its scope and basis, through the [grant lifecycle operation](#grant-lifecycle), unless law prohibits the report or the client has no current client authentication for the grant. + +**Reports and records.** The client SHOULD report its receipt of each instruction and the completion of deletion through the [grant lifecycle operation](#grant-lifecycle). A report needs current client authentication, which a public client usually lacks after its grant ends. Such a client SHOULD then ask the owner to approve [lifecycle recovery](#lifecycle-recovery) at the owner's next interaction with it, and report the times it recorded. A late report keeps the recorded event time. It MUST keep a record of each instruction: receipt time, stop-use time, completion time, any exception, and the parties it informed. The record holds identifiers, not the deleted data. PDPP defines no proof of deletion. + +**Processing authority.** From an instruction's effective time, when it covers data that a grant of the same client carrying a processing permission also covers, the AS MUST issue no further processing authority for that data ([Read access and processing authority](#processing-authority)). The AS MUST show the owner the time by which that processing stops under the defining profile, for example "training on this data stops by 21:40". A client that has not learned of an effective erasure instruction MAY exercise processing authority issued before its effective time only within the defining profile's delivery-independent cessation bound. On learning of the instruction, it MUST apply the defining profile's immediate stop requirements. No authority issued at or after the effective time authorizes use of the covered data. This limited continuation does not override an independently applicable retention or overdue-disposal deadline. An advance instruction has the effects defined in [Ending paths](#ending-paths). + +**AS records and owner statements.** For each instruction, the AS MUST record separately its acceptance time and the time it first returned the instruction in a lifecycle answer. It MUST also record, separately, the receipt time and any completion or exception that a client reports. When the owner chooses `delete`, the AS MUST state the applicable scope and exceptions. It MUST state that the client learns of the instruction only when it obtains an answer from the AS, which it attempts daily while it runs. It MUST state that an attempt is not an answer, and that there is no maximum delivery delay. It MUST state what happens if the AS stops answering for good before the client receives the instruction. For a grant without a processing permission, the client may keep and use the data until the grant's retention ceiling, or indefinitely when the grant states no retention limit. For a grant that carries a processing permission, it MUST state that the client may keep the data but gains no use or processing authority. The stop-use bound is measured from the instruction's effective time and applies when the client receives the instruction by that deadline; a client that learns later must stop at once. The deletion bound runs from the client's first receipt. Endpoint reachability alone does not establish timely receipt. The AS MUST describe these as duties of conforming clients, not proof of remote deletion. For example: "The app must stop using covered data as soon as practicable after it receives this request: by [stop-use date] if it receives it by then, and at once if it receives it later. It must delete covered data within 30 days of receiving the request. While the app runs, it tries daily to check with your server, but a try is not a received request. An app that is not running does not check, and learns of this request only when it next runs and checks. If your server is offline, the app cannot learn of the request until your server answers, and there is no maximum delay. If your server never answers again, the app may keep using the data for the approved purpose until [retention ceiling], or with no time limit if it stated none. If the app offers deletion, deleting inside it binds the app at once. That is an instruction, not instant physical deletion. Legally required copies and the stated exclusions may remain." For an advance election, the stop-use bound runs from the displayed effective event. The deletion deadline runs from the client's first authenticated receipt plus the deletion bound, subject to any earlier retention ceiling. + +The AS MUST NOT show a receipt-based deletion deadline calculated from its acceptance time or from its first return of the instruction. It MAY show a date measured from a reported receipt time. The arrival of a request that reports no receipt time is not a reported receipt time. It MUST show which stages it has recorded: requested, sent, receipt reported, and completion or exception reported. Until a receipt is reported, it MUST show the latest recorded stage and no deletion date, for example "sent on 2 November; no receipt reported". + +#### Downstream holders {#downstream-holders} + +A client MAY let another party hold or process PDPP data for it only within the authority that the client holds. The client MUST impose the grant's purpose and retention on that party. The client MUST impose these held-data duties on that party. The client MUST impose the [AI training](#ai-training) restriction on that party. + +The client MUST NOT treat a party's independent use of the data as processing for the client. An arrangement that permits such use is subject to [Independent-recipient disclosure](#independent-recipient-disclosure). + +The client MUST relay every erasure instruction to each party acting for it. The client MUST relay the deadlines as absolute times. The party's deadlines are the client's deadlines; a relay never starts a new period. The client MUST keep a record of the parties it informed and their confirmations. + +These duties create no authority for independent-recipient disclosure. Section 3 separately prohibits token transfer. + +#### Independent-recipient disclosure {#independent-recipient-disclosure} + +A client MUST NOT disclose PDPP data to an independent recipient unless a registered processing permission expressly covers that disclosure. The client MUST hold valid processing authority under the permission's defining profile when it discloses the data. + +This version defines no processing permission for independent-recipient disclosure. Ordinary access therefore does not authorize that operation. The restriction applies while the grant is active and after it ends. It includes disclosures through records, derivatives, summaries, outputs, and services that reveal PDPP data. + +A client MUST NOT infer disclosure authority from the grant's purpose, retention, an owner's action instruction, client claims, a positive assessment, or read-token activity. A client MUST NOT infer that authority from an exception to erasure or retention. + +A client MAY disclose data to the owner within the grant's applicable use terms. Delivery to an account, device, or service that the owner controls and designates for receiving the data, such as the owner's own email or storage, is disclosure to the owner. A destination that a third party controls is not: a party that the owner directs to receive the data for its own use, such as an accountant, adviser, or lender, is an independent recipient. A client MAY use parties acting for it as [Downstream holders](#downstream-holders) permits. An RS MAY disclose owner-held data under a fresh grant to the receiving client, as Section 3 describes. These permissions do not transfer a grant or token. + +This restriction does not prohibit a disclosure that applicable law requires. A client relying on that exception MUST limit the disclosure to what the obligation requires. The client MUST record the data disclosed, recipient, time, and legal obligation, unless law prohibits that record. The exception confers no processing permission. It does not alter the grant's other duties. + +**Note (non-normative).** This is a client conformance duty. The RS cannot prevent disclosure of a copy already delivered. A future registered permission needs a complete disclosure contract; a permission identifier alone does not define recipient authority or recall a delivered copy. + +**Note (non-normative).** A hosted model or other processing provider acts for the client only when it is bound by the client's duties under [Downstream holders](#downstream-holders) and makes no independent reuse of the data. A provider that may use the data for its own training, product improvement, or other purposes is an independent recipient for that use. + +**Example (non-normative).** A budgeting client holds transactions under an analytics grant. It can show a summary to the owner while its use terms permit. A storage service acting only for the client remains subject to the client's held-data duties. Sending the transactions or summary to an independent lender is a different operation. The analytics purpose and the owner's instruction to send do not create a registered processing permission. In this version the client has no PDPP authority for that disclosure. The owner can instead authorize the lender as a separate client at an owner-held resource server, where available and independently permitted. + +**Example (non-normative).** A test detail contains `processing_permissions: ["urn:example:processing:independent-disclosure"]`. The URI is an intentionally unregistered test value. An AS rejects the detail with `invalid_authorization_details`; it does not omit the permission and issue an ordinary grant. A production client first checks discovery and does not request an unadvertised permission. + +### Grant lifecycle operation {#grant-lifecycle} + +The grant lifecycle operation tells a client whether it may keep and use a grant's held data, and delivers erasure instructions. It also accepts the client's erasure reports. Every AS MUST provide it. It confers no read access and no processing authority, and it reopens no read window. + +**Note (non-normative):** The operation follows consent and grant status queries that a client makes under its own authority. Examples are the grant query in FAPI Grant Management and the consent status queries in UK Open Banking, the Berlin Group, and Plaid payment consents. Neither of those defines duties for data a recipient already holds. Accepting a retired data token to authenticate a public client's query is specific to PDPP. It confers no data or write authority. + +**Discovery.** In the OAuth binding, the AS MUST advertise the operation as `pdpp_grant_lifecycle_endpoint` in its RFC 8414 metadata. The operation is distinct from the read status that the extended access profile reports for package children (`pdpp_grant_read_active`). + +**Request.** The client sends an HTTP `POST` to the endpoint with an `application/x-www-form-urlencoded` body. A request without `report` or `pdpp_disposition` is a query. + +| Parameter | Required | Meaning | +|---|---|---| +| `grant_id` | yes | The grant asked about. A confidential client MAY repeat the parameter to ask about several grants in one query. A public client MUST send it once. | +| `token` | for a public client | An access token or refresh token that the AS issued to the client and that covers the grant. | +| `token_type_hint` | no | `access_token` or `refresh_token`, as in RFC 7009. | +| `report` | no | A write: `received`, `completed`, or `retained`. | +| `instruction_id` | with `report` | The erasure instruction the report concerns. | +| `reported_at` | with `report`; optional with `pdpp_disposition` | RFC 3339 time of the reported event: the client's first receipt, the completion of deletion, or the completion of deletion apart from legally retained data. With `pdpp_disposition`, the time the owner chose `delete` in the client. | +| `retained_until` | with `report=retained` | End of the legal retention obligation, in one of three forms: an RFC 3339 date-time; `event:` followed by text that contains at least one non-whitespace character and names the event or condition that ends it; or `unknown`. | +| `retention_basis` | no | With `report=retained`: a short statement of the legal basis. The client sends it unless law prohibits it. | +| `retention_scope` | no | With `report=retained`: a short statement of which covered data the client keeps. The client sends it unless law prohibits it. | +| `pdpp_disposition` | no | A write with the value `delete`: an owner's erasure request made in the client. | + +A write MUST name exactly one grant. The AS MUST reject, with HTTP 400 `invalid_request`, a malformed request, a missing required parameter, an unknown parameter value, and a request that carries both `report` and `pdpp_disposition`. + +**Authentication.** + +- **Queries.** A public client authenticates with `token`. The AS MUST accept any access token or refresh token that it issued to that client and that covers the grant, whether active, expired, superseded, or revoked. A package token covers each of its children. A confidential client MUST authenticate as at the token endpoint. It MAY omit `token`; the AS then authorizes each `grant_id` by checking that it issued that grant to the client. A token bound to a key under [RFC 9449](https://www.rfc-editor.org/rfc/rfc9449) (DPoP) MUST come with a valid DPoP proof for that key. +- **Writes.** A write needs current client authentication. For a confidential client, that is client authentication as at the token endpoint. For a public client, it is an access token that is active, the current refresh token of a family, or an unexpired [lifecycle recovery](#lifecycle-recovery) token, covering the grant, with a DPoP proof when the token is bound. An expired, superseded, or revoked token never authenticates a write. +- **Assertions and proofs.** A client that authenticates with a JWT assertion ([RFC 7523](https://www.rfc-editor.org/rfc/rfc7523)) MUST set its `aud` to the AS issuer identifier and MUST include a non-empty `jti` string that uniquely identifies the assertion for that client. The AS MUST reject an assertion with any other audience or with a missing or empty `jti`. It MUST reject reuse of a `jti` already accepted for that client while the previously accepted assertion remains valid. A DPoP proof MUST carry `htm` `POST` and an `htu` equal to the lifecycle endpoint URL. When `token` is an access token, the proof MUST carry `ath` for that token. The AS MUST check the proof as RFC 9449 Section 4.3 defines, including `jti` replay detection. +- **Compromise.** The AS MAY disable a token for lifecycle use when it learns that the token is compromised. It MUST be able to disable any token it issued, including one never presented to this operation. It MUST then refuse that token for this operation. Disabling ends no grant, records no disposition, and changes nothing else. +- **Recovery.** A client whose tokens are disabled for lifecycle use MUST be able to recover lifecycle access without a new data grant and without read access. For a confidential client, client authentication is that path. For a public client, the AS MUST support [lifecycle recovery](#lifecycle-recovery). +- **Storage.** For this operation the AS MUST keep digests of tokens, not the tokens themselves. It keeps them as long as [Lifecycle durability](#lifecycle-durability) requires it to keep the grant's lifecycle and authentication bindings. + +**Response.** On success the AS returns HTTP 200 with `Content-Type: application/json`, `Cache-Control: no-store`, and `Pragma: no-cache`. The body is an object with one member, `grants`: an array with one entry per requested `grant_id`, in request order. Each entry is a lifecycle answer or a per-grant error. + +| Member | Type | Meaning | +|---|---|---| +| `grant_id` | string | The grant. | +| `assessed_at` | RFC 3339 | When the AS computed the answer. | +| `read_state` | enum | `active`: the grant can authorize reads. `window_closed`: the read window of a `single_use` grant has ended, and the grant has neither expired nor been revoked. `expired`. `revoked`. | +| `ended_at` | RFC 3339 | When the grant expired or was revoked. Present only for those two states. A grant has one ending: see below. | +| `held_data` | enum | `permitted`: no erasure instruction has taken effect, and the answer is a positive assessment. `erase`: an erasure instruction has taken effect. | +| `erasure` | object | Present only when `held_data` is `erase`: `{ instruction_id, accepted_at, effective_at, stop_use_by }`. `stop_use_by` is the effective time plus the stop-use bound. | + +A grant keeps its first ending. If it is revoked before `expires_at`, `read_state` stays `revoked` and `ended_at` stays the revocation time after `expires_at` passes. Otherwise, from `expires_at`, `read_state` is `expired` and `ended_at` is `expires_at`. A later revocation attempt, disposition, or erasure request for an ended grant does not change its `read_state` or `ended_at`. + +A per-grant error is `{ grant_id, error }`, where `error` is one of: + +- `invalid_grant`: the grant is unknown, was not issued to the client, or is not covered by the presented token. The AS MUST use the same entry schema and error in each of these cases, echoing only the requested `grant_id`, so that a caller cannot tell them apart. +- `current_authentication_required`: a write lacked current client authentication. +- `invalid_instruction`: `instruction_id` names no erasure instruction of that grant. + +Request-level failures use the error response of RFC 6749 Section 5.2. A malformed request gets HTTP 400 `invalid_request`, and failed client authentication gets HTTP 401 `invalid_client`. A `token` that is unknown, malformed, issued to another client, or disabled for lifecycle use gets HTTP 401 `invalid_token`. When the AS cannot compute an answer from ordered state ([Lifecycle durability](#lifecycle-durability)), it returns HTTP 503 `temporarily_unavailable` with `Retry-After`. The AS MAY rate-limit the operation with HTTP 429, but MUST admit at least one query per grant per retry interval from each client. + +**Writes.** + +- `report=received` reports the client's first authenticated receipt of the instruction; `reported_at` is the receipt time. A receipt time before the AS first returned the instruction is valid when the owner's choice in the client was the receipt. +- `report=completed` reports that deletion is complete; `reported_at` is the completion time. +- `report=retained` reports that deletion is complete except for data kept under a legal obligation, with `retained_until` and, unless law prohibits them, `retention_basis` and `retention_scope`. It is an exception, not completion. When the obligation ends and the client deletes the retained data, it reports `completed`. +- `pdpp_disposition=delete` conveys an immediate erasure request. The AS MUST end the grant if it has not ended. If an advance instruction exists, it becomes effective at that ending. If an effective instruction exists, the AS returns it without changing its clocks. Otherwise the AS records a new instruction whose acceptance and effective times are the time it durably records the request. The owner's choice in the client is its first authenticated receipt. When `reported_at` is present, the request also reports that receipt, and the AS MUST record that event time under the rules for `report=received`. When it is absent, the AS records the erasure request but MUST NOT infer a receipt time or a receipt-based deadline from the request's arrival. The client's receipt and deadlines remain the owner's choice time. + +The AS MUST reject, with `invalid_request`, a `reported_at` later than the request, a `retained_until` in none of its three forms, and a date-time `retained_until` earlier than `reported_at`. The AS records the first `received` report and the first `completed` report for an instruction. A repeated report of that kind succeeds and changes nothing. Each `retained` report is kept with the time the AS received it; a later one with a different `retained_until`, `retention_basis`, or `retention_scope` corrects the earlier one and does not overwrite it. The AS MUST NOT show a `retained` report, or the absence of a report, as completed deletion. It MUST show the end of a `retained` report in the form the client gave: a date, the event or condition, or that the end is unknown. The entry returned for a write is the lifecycle answer after the write. + +**Example.** A confidential client queries three grants: + +```http +POST /oauth/grant-lifecycle HTTP/1.1 +Host: as.example.com +Content-Type: application/x-www-form-urlencoded + +grant_id=grt_001&grant_id=grt_8f72a1b3&grant_id=grt_unknown&client_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Ajwt-bearer&client_assertion=eyJhbGciOiJFUzI1NiIs... +``` + +```json +{ + "grants": [ + { + "grant_id": "grt_001", + "assessed_at": "2026-11-02T08:00:03Z", + "read_state": "revoked", + "ended_at": "2026-10-20T17:42:10Z", + "held_data": "permitted" + }, + { + "grant_id": "grt_8f72a1b3", + "assessed_at": "2026-11-02T08:00:03Z", + "read_state": "revoked", + "ended_at": "2026-11-01T21:14:09Z", + "held_data": "erase", + "erasure": { + "instruction_id": "ers_Q2v7Lk9w", + "accepted_at": "2026-11-01T21:14:09Z", + "effective_at": "2026-11-01T21:14:09Z", + "stop_use_by": "2026-11-03T21:14:09Z" + } + }, + { "grant_id": "grt_unknown", "error": "invalid_grant" } + ] +} +``` + +The first grant was revoked with `keep`: the answer is a positive assessment. The second carries an erasure instruction. If this is the first answer to carry it, the client records the time it received the answer as its first receipt. It stops using that grant's data by `stop_use_by` and deletes it within the deletion bound of that receipt. + +**Example.** The same client later reports that it deleted the second grant's data, except invoices that a tax audit requires it to keep until the audit closes: + +```http +POST /oauth/grant-lifecycle HTTP/1.1 +Host: as.example.com +Content-Type: application/x-www-form-urlencoded + +grant_id=grt_8f72a1b3&report=retained&instruction_id=ers_Q2v7Lk9w&reported_at=2026-11-20T09%3A00%3A00Z&retained_until=event%3Aclose%20of%20the%202026%20tax%20audit&retention_basis=tax%20record-keeping%20law&retention_scope=invoices%20for%202026&client_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Ajwt-bearer&client_assertion=eyJhbGciOiJFUzI1NiIs... +``` + +The AS shows the owner that deletion is complete except for the invoices, kept until the close of the 2026 tax audit. When the audit closes and the client deletes the invoices, it reports `completed`. If the client does not know when the obligation ends, it sends `retained_until=unknown`. + +#### Lifecycle recovery {#lifecycle-recovery} + +An authorization request MAY carry one `authorization_details` element of type `https://pdpp.dev/grant-lifecycle`, with `grant_ids` containing a non-empty array of distinct, non-empty grant identifier strings. Every AS MUST support this type and advertise it in `authorization_details_types_supported`. A recovery request MUST contain no other authorization detail and MUST NOT request read or processing authority. The AS MUST reject a malformed or mixed request with `invalid_authorization_details`. + +The AS MUST authenticate the owner and verify that it issued each named grant to the requesting client for that owner, including when the grant has ended. It MUST reject the element with `invalid_authorization_details` when any grant fails that check, without revealing which grant failed. Before approval it MUST show the client, source, purpose, and issue date of each grant. It MUST state that recovery permits lifecycle queries, erasure reports, and client-conveyed erasure requests for those grants, but gives no read or processing authority. The approved grant identifier set and client binding MUST be fixed in the approval artifact and retained consent evidence. + +On approval, the token response issues a lifecycle-only access token for exactly the approved grants, returns the approved recovery element in `authorization_details`, and returns no refresh token. The token authenticates queries through the `token` parameter. It authenticates writes while it is unexpired and has not been revoked or disabled for lifecycle use. The AS MAY give it an expiry; absence of an expiry does not make it expired. The AS SHOULD keep a recovery token valid for lifecycle writes until at least the deletion bound after the client's first authenticated receipt of each covered instruction. When the AS has recorded no receipt, that period runs from issuance. This lets a public client report completion. Its lifecycle validity is separate from introspection `active`: introspection MUST report `active: false`, and the RS MUST reject it. Issuance MUST NOT create or reopen any data grant, read window, or processing authority. Recovery token responses are not positive assessments; the client queries lifecycle state after recovery. Recovery is also how a public client reports receipt and completion after its grant has ended and its tokens can no longer authenticate a write ([Erasure](#erasure)). An expired, superseded, or revoked data-access token never authenticates a report. A client SHOULD resend a report that the AS refused because its credential had expired, once it holds a credential that authenticates the write. + +### Lifecycle durability {#lifecycle-durability} + +Terminal events are revocations, dispositions, and erasure instructions. Once the AS acknowledges a terminal event, no answer, token, or processing authority that it returns afterwards may contradict it. The following rules generalize that invariant. + +The rules in this section that concern a restore, failover, or rollback bind every such path that the AS declares its mechanism detects, and on such a path the AS fails closed as they require. A path that the mechanism does not detect, such as a revert of a virtual-machine snapshot on a single host, is a limitation of the deployment, not a conformance failure. After such a path, an enforcement point may act on history that omits an acknowledged event. The AS MUST disclose that limitation in its durability statement below. Core requires no witness outside the deployment. The AS MUST NOT declare that its mechanism detects a path on which it does not fail closed. + +- The AS MUST record each terminal event durably before it acknowledges the event to the owner or to a client. +- That record MUST be totally ordered against the AS's issuance of tokens, processing authority, and positive assessments. A backup restore or a failover through a path that the AS declares its mechanism detects MUST NOT make any enforcement point act on a history that omits an acknowledged terminal event. +- Every path that issues a credential for a grant, authorizes a read under it, or assesses it is an enforcement point. These paths include, among others, token responses of every grant type: the authorization-code, device-code, and refresh-token exchanges, and re-delivery of a token already minted. They also include issuance of processing authority, introspection, lifecycle answers, and authentication of lifecycle writes. They include any read authorization made without introspection, such as a package fan-out that resolves its children's status directly. Each path MUST compute its result from state that includes every terminal event acknowledged before the computation. This binds the RS, or any other component, that makes one of these decisions without asking the AS. +- A resource server MAY authorize a read using an introspection result cached under Section 8 within its original cache lifetime and applicable read deadline. That result's original computation MUST meet the ordering rule. Its cache lifetime runs from the time the RS sent the introspection request. A delayed response, restore, replay, or clock discontinuity MUST NOT restart it. This exception permits only the bounded read-access propagation in Section 10; it permits no positive assessment, credential issuance, or lifecycle write authentication. A read path that establishes status directly instead of using such a cached result MUST establish current ordered state. +- A replica or restored store may be unable to show that it includes those events. The AS MUST NOT then use it to report a revoked grant active, to issue or re-deliver a token for that grant, or to issue processing authority. It MUST NOT use it to authenticate a write or to return a positive assessment. The lifecycle operation then returns `temporarily_unavailable` for the grant, with one exception. A lifecycle answer whose `held_data` is `erase` MAY come from such state, but only when the complete instruction was durably effective before that state lost currency: its `instruction_id`, `accepted_at`, `effective_at`, and `stop_use_by`, and every grant-ending fact it returns. The AS MUST NOT promote an advance election to an effective instruction, or infer an effective time, from stale state. A refusal or an inactive introspection result MAY also come from such state. A terminal event is never undone, so these answers stay true. The AS still records its first return of an instruction ([Erasure](#erasure)). +- A restore of the data that read enforcement uses MUST NOT reopen reads under a grant whose revocation the AS acknowledged. +- Once the AS shows the owner a time by which processing stops, no processing authority it returned before or returns after may permit processing past that time. +- After a restore or failover through a declared path, an enforcement point MUST NOT treat a history as current until it establishes that the history includes every acknowledged terminal event. The AS chooses and declares the mechanism. Examples are loss-detection evidence kept outside the history's failure domain, and invalidation on restore of every grant whose terminal events may be missing. With a single store and no evidence outside it, that is in practice every grant affected by the undetectable window, and re-establishing those grants needs authoritative facts from outside the restored store. Before acknowledging a terminal event, the AS MUST durably advance whatever evidence its mechanism uses. Evidence MAY lag events that have not been acknowledged. If an enforcement point cannot establish currency, it MUST fail closed as this section requires until authoritative facts are recovered. History whose currency is unknown never yields a positive assessment, a credential, lifecycle write authentication, or renewed read authority. +- Grant issuance, consumption of a `single_use` grant, authorization-code redemption, refresh-token supersession, and assignment of a `grant_id`, an erasure `instruction_id`, or a pairwise identifier are also recorded events. The AS MUST record each durably before it returns a response that discloses or relies on it. On a declared restore or failover path, the currency rule above applies to these events as to terminal events: a history that may omit one is not current, and an enforcement point fails closed. A `grant_id` and an `instruction_id` are non-empty strings. The AS MUST NOT reuse either after any restore, failover, or rollback, whether or not its mechanism detects it. For example, it generates them with enough randomness that a restored counter cannot repeat them. On a declared path, it MUST NOT reassign a pairwise identifier. +- While the AS cannot establish a grant's history, it MUST fail closed for that grant: it issues and re-delivers no token, issues no processing authority, reports no active introspection result, and returns no positive assessment. It MUST NOT rebuild an active grant from an older backup. The lifecycle operation returns `temporarily_unavailable` with `Retry-After`, except for an answer that the bullet above permits. +- While its history is unavailable, the AS MUST still accept an owner's revocation, disposition, or erasure request, and MUST NOT reject one for that reason. It MUST record each such request durably before it acknowledges it, and MUST apply each to the history before any answer for the affected grant once the history is re-established. It MAY return a recorded erasure instruction at once, as the bullet above permits. It MUST show the owner that the action is recorded and pending, and that the AS issues no tokens or processing authority and returns no positive assessments for the affected grants meanwhile. It MUST explain that read access ends within Section 10's bounded propagation period; an existing cached introspection result can permit reads only within its original cache lifetime and applicable read deadline. +- For an action affecting several grants, the AS MUST durably record a result for each grant. It MUST NOT report the action complete until every requested grant ending and every requested disposition has been durably recorded. A partial result MUST identify each grant as recorded or pending, without treating a pending result as complete. +- The AS MUST show the owner whether each terminal event is pending or recorded. It MUST describe the durability it actually provides, including its restore mechanism, the disk and host losses it does not survive, and the restore and rollback paths its mechanism does not detect. It MUST state that a rollback it does not detect, such as a revert of a virtual-machine snapshot, can revive revoked grants and lose recorded deletions, unless the deployment declares a mechanism that detects it. It MUST also state that such a rollback can revive consumed `single_use` grants, redeemed authorization codes, and superseded refresh tokens. An AS that keeps its history on a single disk MUST NOT claim that the record survives loss of that disk. +- The AS MUST retain the grant's lifecycle and authentication bindings while the grant can authorize further reads or processing, while held-data duties remain unresolved, or while legally retained data may remain. Passing a retention ceiling does not establish completed deletion. The AS MUST retain effective erasure instructions, reported exceptions, and the bindings needed for queries and reports until those duties are resolved. It MAY compact resolved history to minimal terminal records, but MUST preserve the facts needed to prevent a restore, replay, or later issuance from reviving ended authority or cancelling erasure. These records MUST NOT contain deleted source data. + +### Retention {#grant-retention} Retention is a structured policy declaration and policy commitment by the data recipient (the client). PDPP does not technically enforce retention. Enforcement is through legal agreements or contractual obligations; a trust registry supports admission and accountability for a retention commitment rather than enforcing it, because Core defines no compliance-evidence query a registry could answer. This is consistent with how OAuth 2.0 treats scope compliance: the protocol makes the commitment legible and machine-readable; external mechanisms enforce it. ```json { - "max_duration": "P6M", + "max_duration": "P180D", "on_expiry": "delete" } ``` | Field | Type | Description | |-------|------|-------------| -| `max_duration` | ISO 8601 duration | How long the client may retain collected data. | -| `on_expiry` | enum | `delete` or `anonymize`. Note: `archive` is not supported in v0.1. | +| `max_duration` | ISO 8601 duration in days (`PnD`) | How long the client may retain each record, counted from its first acquisition. | +| `on_expiry` | enum | `delete` or `anonymize`, applied at each record's retention ceiling. An erasure instruction always requires deletion. Note: `archive` is not supported in v0.1. | + +In v0.1, `max_duration` MUST have the form `PnD`, where n is a positive whole number of days, such as `P90D`. A day is 24 hours of elapsed time. The AS MUST reject any other form, including months, years, weeks, and time components, with `invalid_authorization_details` in the OAuth/RAR binding. A client that receives a `max_duration` in any other form MUST treat it as invalid and fail closed: it treats each covered record's retention ceiling as already reached. A record's retention ceiling is the client's first acquisition of that record plus `max_duration`. Rereading, transforming, relabeling, moving, or deriving data never restarts that clock. Neither does obtaining a later grant or processing authority. A later version of a record that the client receives counts from its own receipt. Where the client cannot tell which version a copy came from, the earliest acquisition governs. A derivative is subject to the ceiling of every record it was derived from. + +At a record's retention ceiling, the client MUST complete the `on_expiry` action for that record and its derivatives, with no further grace period, subject to the learned-parameter exception in [Held data after a grant ends](#held-data). `anonymize` is complete only when the data is non-identifiable as [Erasure](#erasure) defines, under a test the client states in its records. Removing direct identifiers while keeping a per-owner key, hash, or identifier does not complete it. A client that cannot complete qualifying anonymization by the ceiling MUST delete the data by then. Retention is a maximum. It never permits a new purpose, a processing permission, or keeping data that an erasure instruction requires the client to delete. An owner's choice can shorten it and never extends it. Absent `retention` means no stated limit, which final owner review states ([Recipient commitments and approval](#recipient-commitments)). ### Examples @@ -1065,7 +1601,7 @@ Retention is a structured policy declaration and policy commitment by the data r "version": "0.1.0", "grant_id": "grt_001", "issued_at": "2026-04-06T15:00:00Z", - "subject": { "id": "user_abc" }, + "subject": { "id": "sub_x7Pd2KfL" }, "client": { "client_id": "concert_app" }, "source": { "kind": "connector", "id": "https://registry.pdpp.dev/connectors/spotify" }, "source_declaration": { "version": "2026-08-11" }, @@ -1074,7 +1610,7 @@ Retention is a structured policy declaration and policy commitment by the data r "streams": [ { "name": "top_artists", - "instance_ids": ["spotify-account-a"], + "instance_ids": ["inst_9fQ2xLp7"], "fields": ["id", "name", "genres", "popularity", "source_updated_at"], "time_constraint": { "field": "source_updated_at", @@ -1092,7 +1628,7 @@ Retention is a structured policy declaration and policy commitment by the data r "version": "0.1.0", "grant_id": "grt_002", "issued_at": "2026-04-06T15:00:00Z", - "subject": { "id": "user_abc" }, + "subject": { "id": "sub_R3mV9cYe" }, "client": { "client_id": "personal_agent" }, "source": { "kind": "connector", "id": "https://registry.pdpp.dev/connectors/openai" }, "source_declaration": { "version": "2026-08-11" }, @@ -1101,25 +1637,27 @@ Retention is a structured policy declaration and policy commitment by the data r "streams": [ { "name": "conversations", - "instance_ids": ["openai-account-a"], + "instance_ids": ["inst_Hc7vM3sD"], "fields": ["id", "title", "source_created_at", "source_updated_at"] }, { "name": "messages", - "instance_ids": ["openai-account-a"], + "instance_ids": ["inst_Hc7vM3sD"], "fields": ["id", "conversation_id", "role", "content", "source_created_at"] } ] } ``` +This grant permits ordinary agent-context use; it does not authorize the agent to disclose conversation content or a derived summary to an independent recipient. + **Health data with field selection and retention:** ```json { "version": "0.1.0", "grant_id": "grt_003", "issued_at": "2026-04-06T15:00:00Z", - "subject": { "id": "user_abc" }, + "subject": { "id": "sub_bT6nW1qZ" }, "client": { "client_id": "sleep_analysis" }, "source": { "kind": "connector", "id": "https://registry.pdpp.dev/connectors/oura" }, "source_declaration": { "version": "2026-08-11" }, @@ -1128,7 +1666,7 @@ Retention is a structured policy declaration and policy commitment by the data r "streams": [ { "name": "sleep_sessions", - "instance_ids": ["oura-account-a"], + "instance_ids": ["inst_P2xf9Lb6"], "fields": ["day", "total_sleep_duration", "sleep_score"], "time_constraint": { "field": "day", @@ -1148,7 +1686,7 @@ Retention is a structured policy declaration and policy commitment by the data r **Note:** This section defines the interoperable record-query and blob-fetch interface under grant enforcement. Authorization-server deployment, storage backend, collection runtime, operator dashboard, and hosted service choices are out of scope for this document. -The resource server stores records and serves them to clients filtered by grants. This section is normative: a compliant resource server must implement this interface for cross-deployment interoperability. +The resource server stores records and serves them to clients filtered by grants. A conformant resource server MUST implement this interface for cross-deployment interoperability. ### Grant enforcement @@ -1169,6 +1707,22 @@ The RS MUST NOT re-validate authorization against the current SourceDeclaration. **Token type distinction:** The format of the access token is opaque to the Resource Server. The RS MUST determine the token's properties (including `pdpp_token_kind`) solely from the introspection response, never from token syntax. +### Existing permissions and action results {#existing-permissions} + +PDPP grants govern the data surface named in the grant. Provider-defined permissions continue to govern actions such as posting, sending, editing, and deleting. A PDPP data grant MUST NOT authorize those actions. + +For an operation using PDPP-governed data access, the RS MUST enforce the resolved grant independently of provider action permission. Existing broad read scopes MUST NOT widen that grant. Legacy interfaces MAY retain their existing permission model outside the declared PDPP surface. + +When an operation needs both permissions, the server MUST verify both before execution. Denial of action permission MUST NOT cancel independently approved reads unless the authorization transaction explicitly requires both. + +An action may use source-side data under its provider authorization. This does not authorize disclosure of that data to the client. An action response containing existing PDPP-governed records or facts derived from them MUST satisfy the applicable data grant. + +A server MAY return a minimal action receipt under the action permission alone. Such a receipt is limited to operation status, values supplied by the caller, and a newly generated opaque operation or resource identifier. Status MUST describe only the outcome of the authorized action. The receipt MUST NOT reveal pre-existing field values, unrelated record existence, or private associations, or confer permission to retrieve source data. + +If the action response would disclose unauthorized data, the server MUST redact that data or refuse the operation. The server MUST resolve a predictable disclosure failure before performing the side effect. An unexpected post-action failure MUST NOT cause broader disclosure; the provider's action protocol governs retry and recovery. + +The optional [extended access profile](spec-access-extension) defines owner-selected authorization, grant packages, and bounded presentation reads. These features do not add operations to the Core query interface. + ### Token introspection For separated AS/RS deployments, the RS MUST authenticate to the AS introspection endpoint as required by RFC 7662. The introspection response combines standard RFC 7662 fields with PDPP-defined extensions: @@ -1177,20 +1731,27 @@ For separated AS/RS deployments, the RS MUST authenticate to the AS introspectio |-------|------|-------------| | `active` | boolean | Whether the token is currently valid. | | `pdpp_token_kind` | string | `"owner"` or `"client"`. | -| `subject_id` | string | The subject (user) identifier. | +| `subject_id` | string | The subject identifier that the RS uses to enforce the request. It MAY be an internal identifier that differs from the grant's pairwise `subject.id`, and the RS MUST NOT disclose it to a client (see [Pairwise identifiers](#pairwise-identifiers)). | | `grant_id` | string | The associated grant identifier. Present for client tokens. | | `client_id` | string | The client identifier. Present for client tokens. | | `exp` | integer | Expiry timestamp (Unix epoch). Present in every positive response for a token that has an expiration, including every client token issued against a `single_use` grant. Omitted when the token has no expiration. | -| `authorization_details` | array | The approved RFC 9396 detail for a client token. It carries the resolved grant enforcement constraints defined in Section 7. | +| `authorization_details` | array | One `{ type, grant }` element per authorized grant, using the same shape as the [client-visible authorization result](#authorization-result) in Section 7. | +| `pdpp_instance_bindings` | array | RS-only. Maps each instance handle that the token can use to the instance that the RS stores. For a client token, there is one entry `{ source_id, stream, instance_id, rs_instance }` for each stream and handle in the grant. For an owner token, there is one entry `{ source_id, instance_id, rs_instance }` for each instance in the owner's connection scope, with the owner's handle. `rs_instance` is an opaque string that the RS resolves to a stored instance. Every entry for one `(source_id, instance_id)` MUST name the same `rs_instance`; the RS MUST reject conflicting entries as `grant_invalid` before serving data. | + +For a given issuer, subject, and receiving client, the AS MUST assign instance handles that identify only one instance across all sources. The AS MUST apply the same cross-source uniqueness requirement to an owner's handles. A `pdpp_instance_bindings` response MUST NOT contain the same `instance_id` under different `source_id` values. The RS MUST reject such a response with 403 `grant_invalid` before serving data. The introspection response MUST contain the complete context needed to enforce the request. The separated RS MUST enforce only from that response and MUST NOT make a second AS lookup while handling the request. A co-located AS and RS MAY resolve the same context through a local equivalent. +For a client or owner token, that context includes `pdpp_instance_bindings`. A separated RS MUST resolve each handle only through this member and MUST fail closed when a binding is missing. A client request that needs a handle with no binding, or with a binding that names no stored instance, fails with 403 `grant_invalid`. For an owner token, an instance with no binding is outside the owner scope. The AS MUST NOT return `pdpp_instance_bindings` to a client. + **Token kind extensibility:** This specification defines `owner` and `client`. Deployments MAY introduce additional token kinds in companion profiles. A resource server that receives a `pdpp_token_kind` value it does not recognize MUST treat the token as unauthorized for all operations defined in this specification. Positive introspection results MUST NOT be cached longer than `min(token_exp, 60 seconds)`. Self-contained JWTs (e.g., signed JWTs) are allowed as an optimization but MUST NOT be the sole revocation mechanism; the RS MUST still be able to check active status through introspection or local equivalent. ### Authentication +An AS MUST advertise `https://pdpp.dev/data-access` in `authorization_details_types_supported` in its OAuth authorization-server metadata. A client MUST establish support for this type before requesting it. Unknown detail types MUST be rejected. + Two authentication boundaries exist: **Owner operations:** `Authorization: Bearer <owner_token>`. Core owner tokens are scoped to a single subject's data store and support the Core owner and self-export operations defined here. The RS MUST derive the `subject_id` from the introspection response and MUST reject any request attempting to access data outside that subject's scope. Companion profiles may define additional owner-authenticated operations. How the owner obtains this token is out of scope (device code flow, API key, or any other mechanism). @@ -1207,7 +1768,7 @@ A client that reaches the resource server without a usable access token learns t The `resource` member is the resource server's own identifier, as RFC 9728 Section 2 requires. For a `provider_native` source it is the same identifier as the declaration's `source.id`, which is the binding Section 5 already requires an authorization server to check before consent. A resource server that serves several sources publishes one metadata document per resource identifier rather than one document listing them. -PDPP defines four additional members. RFC 9728 Section 2 permits additional parameters and RFC 9728 Section 3.2 requires a reader to ignore any parameter it does not understand, so a generic OAuth client is unaffected by their presence. Each name carries the `pdpp_` prefix to keep it distinct from a future registered parameter; RFC 9728 does not itself prescribe a naming convention. +PDPP defines five additional members. The first four are REQUIRED. `pdpp_freshness_granularity_seconds` is REQUIRED when the resource server attaches `freshness` to a client-token response. RFC 9728 Section 2 permits additional parameters and RFC 9728 Section 3.2 requires a reader to ignore any parameter it does not understand, so a generic OAuth client is unaffected by their presence. Each name carries the `pdpp_` prefix to keep it distinct from a future registered parameter; RFC 9728 does not itself prescribe a naming convention. | Member | Meaning | | --- | --- | @@ -1215,10 +1776,11 @@ PDPP defines four additional members. RFC 9728 Section 2 permits additional para | `pdpp_token_kinds_supported` | The `pdpp_token_kind` values this resource server accepts, drawn from the kinds Section 8 defines. | | `pdpp_self_export_supported` | Whether an owner token may read the owner's own data through the client query endpoints without a client grant. | | `pdpp_provider_connect_version` | The PDPP version this resource server's interface implements, which a client would otherwise learn only from the `PDPP-Version` negotiation on a first request. | +| `pdpp_freshness_granularity_seconds` | An integer of at least 3600: the fixed granularity, in seconds, to which the resource server truncates `last_success_at` in client-token responses (see [Freshness metadata](#freshness)). | `resource_name` is RFC 9728's own member for a human-readable resource name, not a PDPP extension; a resource server SHOULD publish it because a consent surface has no other name to display for the resource. -RFC 9728 Section 2 makes `authorization_servers` OPTIONAL, and notes that in some deployments the set of authorization servers is not enumerable. A PDPP resource server MUST publish `authorization_servers` when that set is enumerable, so a client can reach the issuer without prior configuration. When the set is not enumerable, the resource server MUST omit the member rather than publish a partial list. The client then obtains the issuer from the grant it already holds, or from the deployment's own onboarding. Core defines no other discovery path for that case. +RFC 9728 Section 2 makes `authorization_servers` OPTIONAL, and notes that in some deployments the set of authorization servers is not enumerable. A PDPP resource server MUST publish `authorization_servers` when that set is enumerable, so a client can reach the issuer without prior configuration. When the set is not enumerable, the resource server MUST omit the member rather than publish a partial list. The client then uses the authenticated AS issuer it retained from the OAuth exchange that delivered its grant, or an issuer provisioned through the deployment's trusted onboarding. The grant object contains no issuer identifier, so the client MUST retain the issuer with each grant and MUST NOT infer it from `grant_id`, `source.id`, or an untrusted credential. Core defines no other discovery path for that case. The `capabilities` member is defined by the extension profiles that advertise into it, not by Core. Core neither requires it nor constrains its contents, and a resource server that implements no extension omits it. @@ -1233,7 +1795,7 @@ Authorization: Bearer <access_token> Returns streams with record counts, scoped by token kind: for a client token, the streams present in the resolved authorization context; for an owner token, the streams in the subject-scoped data store the owner token is scoped to. -**Response:** +**Response** (client token; the grant lists two instances for each stream, and the server has never collected `inst_W8nt5Gq1`): ```json { "object": "list", @@ -1242,23 +1804,19 @@ Returns streams with record counts, scoped by token kind: for a client token, th "object": "stream", "name": "conversations", "record_count": 2196, - "last_updated": "2026-04-06T15:01:00Z", - "freshness": { - "captured_at": "2026-04-06T15:01:00Z", - "status": "current", - "last_attempted_at": "2026-04-06T15:01:00Z" - } + "freshness": [ + { "instance_id": "inst_Hc7vM3sD", "last_success_at": "2026-04-06T15:00:00Z" }, + { "instance_id": "inst_W8nt5Gq1", "last_success_at": null } + ] }, { "object": "stream", "name": "messages", "record_count": 48302, - "last_updated": "2026-04-06T15:01:00Z", - "freshness": { - "captured_at": "2026-04-06T15:01:00Z", - "status": "current", - "last_attempted_at": "2026-04-06T15:01:00Z" - } + "freshness": [ + { "instance_id": "inst_Hc7vM3sD", "last_success_at": "2026-04-06T15:00:00Z" }, + { "instance_id": "inst_W8nt5Gq1", "last_success_at": null } + ] } ] } @@ -1274,7 +1832,7 @@ Authorization: Bearer <access_token> A client-token caller may fetch metadata only for a stream present in its resolved authorization context. An owner-token caller may fetch metadata for streams in the subject's data store the owner token is scoped to. Once access is authorized, the response body is actor-specific: - **Owner token:** the metadata document is returned whole — full current schema, query capabilities, views, and relationships — rather than field-projected by any grant. An owner token carries no grant, so there is nothing to project against. -- **Client token:** the response is a closed projection derived from the resolved authorization context: only the granted stream's explicitly granted fields, and only immutable/frozen grant facts. Current query, view, relationship, filter, expansion, and aggregation capabilities MUST NOT appear unless that capability is explicitly part of a future frozen grant vocabulary. Current metadata MAY report availability/freshness or reject an unavailable operation, but MUST NOT make the grant appear broader or semantically different than what was issued. A source declaration change made after the grant was issued (e.g., a new field) MUST NOT become visible through this endpoint for that grant. +- **Client token:** the response is a closed projection derived from the resolved authorization context: only the granted stream's explicitly granted fields, and only immutable/frozen grant facts. Current query, view, relationship, filter, expansion, and aggregation capabilities MUST NOT appear unless that capability is explicitly part of a future frozen grant vocabulary. Current metadata MAY report availability or `freshness` (see [Freshness metadata](#freshness)) or reject an unavailable operation, but MUST NOT make the grant appear broader or semantically different than what was issued. A source declaration change made after the grant was issued (e.g., a new field) MUST NOT become visible through this endpoint for that grant. **Owner-token response** (full current metadata): @@ -1298,11 +1856,13 @@ A client-token caller may fetch metadata only for a stream present in its resolv { "name": "messages", "default_limit": 10, "max_limit": 50 } ] }, - "freshness": { - "captured_at": "2026-04-06T15:01:00Z", - "status": "current", - "last_attempted_at": "2026-04-06T15:01:00Z" - }, + "freshness": [ + { + "instance_id": "inst_Zp5rT2mA", + "last_success_at": "2026-04-06T15:01:07Z", + "last_failure_at": "2026-04-05T09:12:40Z" + } + ], "views": [ { "id": "basic", "label": "Artist names and genres", "fields": ["id", "name", "genres"] } ], @@ -1333,27 +1893,45 @@ A client-token caller may fetch metadata only for a stream present in its resolv "resources": false }, "query": { }, - "freshness": { - "captured_at": "2026-04-06T15:01:00Z", - "status": "current", - "last_attempted_at": "2026-04-06T15:01:00Z" - }, + "freshness": [ + { "instance_id": "inst_K4wq8Rn2", "last_success_at": "2026-04-06T15:00:00Z" } + ], "views": [], "relationships": [] } ``` -#### Freshness metadata +#### Freshness metadata {#freshness} -A resource server MAY attach a `freshness` object to stream listings, stream metadata, and record-list responses. +A resource server MAY attach a `freshness` array to stream listings, stream metadata, and record-list responses. On `/v1/streams`, the array is a member of each stream item. On stream metadata and record lists, it is a top-level member of the response. -Freshness is server-observed disclosure metadata, not a grant constraint. It reports what the server knows about the recency of the underlying data relevant to the response. It does not guarantee that the source has not changed since `captured_at`, and it does not widen or narrow access rights. +Freshness is server-observed disclosure metadata, not a grant constraint. It reports when the server last collected or confirmed data relevant to the query. It does not guarantee that the source has not changed since that time, and it does not widen or narrow access rights. + +The array has one entry for each instance that the query context authorizes for the stream. For a client token, these are the instance handles that the grant lists for the stream. For an owner token, they are the instances of the stream in the owner scope. The array lists every such instance, whatever the page contains, including an instance that the server has never collected. It lists each instance once. The containing stream identifies the stream, so an entry has no `stream` member. | Field | Type | Description | |-------|------|-------------| -| `captured_at` | ISO 8601 or null | Time of the most recent successful collection or source confirmation that could have affected the response. null if unknown. | -| `status` | enum | `current`, `stale`, or `unknown`. `stale` means the server believes the stored data may no longer reflect source state based on local collection policy or failed refresh attempts. | -| `last_attempted_at` | ISO 8601 or null | Time of the most recent attempted refresh relevant to the response, if tracked. | +| `instance_id` | string | The instance handle, as on records: the grant's handle for a client token, and the owner's handle for an owner token. | +| `last_success_at` | RFC 3339 date-time or null | The completion time of the most recent successful collection or source confirmation that could affect records visible under the full authorized scope of the query. | +| `last_failure_at` | RFC 3339 date-time or null | Owner token only. The time at which the most recent failed collection or source confirmation ended, under the same scope rule. | + +**Scope.** The full authorized scope of the query is the stream and the instance. For a client token, the grant's `resources`, `time_constraint`, and field projection restrict it further. Request parameters such as `fields` do not narrow it. An operation qualifies when it could write, change, or confirm a record visible under this scope. A check that covers the authorized data qualifies even when it finds no change. An operation confined to data outside this scope MUST NOT change the value. The value is not clipped to the record time window: a collection in September can add records dated in March. When the resource server cannot establish safely which operations are relevant to the scope, the value is null. + +**Success.** An operation is successful when it completed and its writes were committed. A completed check that found no change is successful. Partial progress within a failed or unfinished operation is not a success. A failed operation is one that ended without success. + +**Null.** A null value means only that the server has no reportable timestamp. It does not prove that nothing was collected or that nothing failed. + +**Failure timing.** A client-token response MUST NOT carry `last_failure_at` or any other failure time. An owner-token response MAY carry `last_failure_at` in each entry. + +**Coarsening.** In a client-token response, the resource server MUST truncate each `last_success_at` value to the granularity that it declares as `pdpp_freshness_granularity_seconds` in its [protected resource metadata](#protected-resource-metadata). The granularity MUST be at least 3600 seconds. The resource server truncates the value down to a multiple of that many seconds in Unix time and expresses the result in UTC. For example, a granularity of 3600 truncates each value to the start of its hour. The resource server MUST NOT report a truncated value before its interval ends. With a granularity of 3600, a success at 10:17 UTC appears as 10:00 UTC from 11:00 UTC onward. Until then, the entry reports the most recent success in an interval that has ended, or null. One granularity applies to every entry in every client-token response. Truncation keeps order: a later success never has an earlier value. A client that polls still sees each change, but only at an interval boundary. These rules limit the precision of the freshness signal. They do not guarantee timing privacy across the whole API. + +**Sync sessions.** When it serves the first page of a `changes_since` session, including one that starts from `beginning`, the resource server takes a snapshot of the `freshness` array. It carries that exact snapshot through the session's page cursors and repeats it unchanged on every later page of the session. + +**No verdict.** Core defines no staleness verdict on the wire. A client that needs one derives it from `last_success_at` and its own policy. + +#### Absence of records {#absence-of-records} + +An empty result reports no entries for that operation. In incremental sync, it does not establish that the authorized stored view is empty. The end of pagination means there are no more pages in that enumeration. A tombstone reports that its identified record left the query's visible set. A record-read 404 reports that the requested record is not visible under that query context. A client MUST NOT infer from these that a record does not exist at the source, or that collection is complete. This applies whatever `freshness` reports. The guarantees that Core makes about the client's synchronized copy of the authorized view still hold (see [Incremental sync](#incremental-sync)). v0.1 defines no signal that supports a claim that data does not exist at the source. #### List records {#list-records} @@ -1393,9 +1971,9 @@ Client-token requests that contain `expand[]` or `expand_limit[...]` MUST be rej For owner-token current-capability reads, range filters (`gte`, `gt`, `lte`, `lt`) apply only to fields declared in `query.range_filters`. On a `date` or `date-time` field, they use the validity and comparison rules in [Time constraint semantics](#time-constraint-semantics), and an invalid value returns 400 `invalid_request`. Nested paths, arrays, OR grammar, and full-text search are not part of v0.1. -For owner-token current-capability reads, expansion is declaration-driven. A relation is structurally present if listed under `relationships`, but it is only expandable if declared under `query.expand`. `expand_limit[{relation}]` is only valid for declared `has_many` relations. +For owner-token current-capability reads, expansion is declaration-driven. A relation is structurally present if listed under `relationships`, but it is only expandable if declared under `query.expand`. `expand_limit[{relation}]` is only valid for declared `has_many` relations. Expansion joins only related records in the parent record's instance. -**Stable sort:** Records are sorted by `(cursor_field, primary_key)` for cursor safety. Null or absent `cursor_field` values sort after present values. A `changes_since` session instead orders records and tombstones together by canonical key string, in the direction `order` selects. It does not follow `cursor_field`, which a tombstone lacks, or the order of changes, which would reveal when a hidden field changed relative to other updates. +**Stable sort:** Records are sorted by `(cursor_field, instance_id, primary_key)` for cursor safety. Null or absent `cursor_field` values sort after present values. A `changes_since` session instead orders records and tombstones together by `instance_id` and then canonical key string, in the direction `order` selects. It does not follow `cursor_field`, which a tombstone lacks, or the order of changes, which would reveal when a hidden field changed relative to other updates. A page cursor is bound to the query context of the first page: the grant (for an owner token, the subject and effective owner scope), stream, `fields`, `view`, `expand[]`, `expand_limit[...]`, `order`, every `filter[...]`, and any `changes_since` token. A client MUST follow a `next_cursor` with the same context that produced it. To change the context, the client MUST restart pagination without a cursor. Resource servers MUST reject a page cursor used with a different context as `invalid_cursor`. @@ -1413,22 +1991,22 @@ If a `changes_since` response is paginated, all pages in that session MUST be an A `changes_since` request with `expand[]` or `expand_limit[...]` is rejected with 400 `invalid_request` for every token kind. An expanded record can change when a related record changes, with no change to the parent record, so a session that compares parent versions would miss it. A client syncs each stream on its own. -**Response:** +**Response** (client token; the grant lists two instances for the stream): ```json { "object": "list", "url": "/v1/streams/conversations/records", "has_more": true, "next_cursor": "pc_Vx3q9LmT0bRk7ZwD2yNf5HsJa8GuPc4e", - "freshness": { - "captured_at": "2026-04-06T15:01:00Z", - "status": "current", - "last_attempted_at": "2026-04-06T15:01:00Z" - }, + "freshness": [ + { "instance_id": "inst_Hc7vM3sD", "last_success_at": "2026-04-06T15:00:00Z" }, + { "instance_id": "inst_W8nt5Gq1", "last_success_at": null } + ], "data": [ { "object": "record", "id": "conv_01JQW8M2R7", + "instance_id": "inst_Hc7vM3sD", "stream": "conversations", "data": { "id": "conv_01JQW8M2R7", @@ -1441,7 +2019,7 @@ A `changes_since` request with `expand[]` or `expand_limit[...]` is rejected wit } ``` -The terminal page of a `changes_since` request (i.e., `has_more: false`) MUST include `next_changes_since`. A terminal `changes_since` page for a client token, with one tombstone and one changed record in the default descending key order: +The terminal page of a `changes_since` request (i.e., `has_more: false`) MUST include `next_changes_since`. This terminal `changes_since` page for a client token has one tombstone and one changed record in the default descending key order. Its `freshness` array is the same on every page of the session: ```json { @@ -1449,16 +2027,22 @@ The terminal page of a `changes_since` request (i.e., `has_more: false`) MUST in "url": "/v1/streams/conversations/records", "has_more": false, "next_changes_since": "cs_7Rk2VqXn9LwT4pZb0HmYc8JdF3sGa1Ue", + "freshness": [ + { "instance_id": "inst_Hc7vM3sD", "last_success_at": "2026-04-06T15:00:00Z" }, + { "instance_id": "inst_W8nt5Gq1", "last_success_at": null } + ], "data": [ { "object": "record", "id": "conv_01JQX2P4K9", + "instance_id": "inst_Hc7vM3sD", "stream": "conversations", "deleted": true }, { "object": "record", "id": "conv_01JQW8M2R7", + "instance_id": "inst_Hc7vM3sD", "stream": "conversations", "data": { "id": "conv_01JQW8M2R7", @@ -1480,6 +2064,8 @@ Authorization: Bearer <access_token> Returns a single record by primary key. The `{id}` path parameter is the percent-encoded canonical key string. Owner-token current-capability reads support `expand[]`; client-token requests reject it in v0.1 before declaration lookup. +The `instance_id` query parameter selects the record's instance. It is REQUIRED when the query context covers more than one instance of the stream. For a client token, that is when the grant lists more than one handle for the stream. For an owner token, it is when the owner scope covers more than one instance. Otherwise `instance_id` is OPTIONAL. The requirement depends only on the query context, not on whether two instances hold the key. The resource server MUST reject a missing required `instance_id` with 400 `invalid_request` before it looks up the record. It returns 404 `not_found` for an `instance_id` that the query context does not cover. + #### Delete a record (owner-authenticated) ``` @@ -1487,22 +2073,24 @@ DELETE /v1/streams/{stream}/records/{id} Authorization: Bearer <owner_token> ``` -Permanently removes a record from the stream. The RS may implement this as a tombstone internally. Returns 204 No Content on success. The `{id}` path parameter is the percent-encoded canonical key string. +Permanently removes a record from the stream. The RS may implement this as a tombstone internally. Returns 204 No Content on success. Deleting a record at the RS is not an erasure instruction, and it creates no duty for a client that already holds the record (Section 12, Record-level erasure and correction). The `{id}` path parameter is the percent-encoded canonical key string. The `instance_id` query parameter follows the rule for a single-record read. #### Get a blob ``` -GET /v1/blobs/{blob_id} +GET /v1/blobs/{blob_id}?instance_id={instance_id} Authorization: Bearer <access_token> ``` +A `blob_id` is unique only within one instance, and a blob request names no stream. The `instance_id` query parameter selects the blob's instance and is REQUIRED on every blob request. The resource server MUST reject a blob request without it with 400 `invalid_request`. The `fetch_url` that the resource server injects MUST include `instance_id`. + The resource server MUST NOT serve a blob unless a record that the requesting token is currently authorized to read references it. It evaluates this on each request. For a client token, it verifies that: -1. The grant includes a stream containing a record that references this `blob_id`. +1. The grant lists the selected instance for a stream in which a record of that instance references this `blob_id`. 2. The referencing record passes all grant filters. 3. The `blob_ref` field is included in the grant's authorized field projection. -For an owner token authorized for blob fetch, the RS applies its subject, source, connection, and operation scope and verifies that a record readable under that scope references the blob. +For an owner token authorized for blob fetch, the RS applies its subject, source, connection, and operation scope and verifies that a record of the selected instance, readable under that scope, references the blob. A `blob_id` alone does not grant access. When no such record exists, the RS returns 404 `blob_not_found`, the same response as for an unknown or stale `blob_id`. @@ -1516,7 +2104,7 @@ A `blob_id` alone does not grant access. When no such record exists, the RS retu - `Location` header pointing to a signed URL - `Cache-Control: no-store` -The signed URL MUST expire no later than the positive-status cache expiry, or, if no result was cached, 60 seconds after token validation; it MUST also expire no later than the access token or grant expiration when present. The AS MUST include `exp` in every positive introspection response for an expiring PDPP token. A signed URL may remain usable after grant revocation until it expires; its lifetime is bounded by the preceding rule. +The signed URL MUST expire no later than the positive-status cache expiry. If no result was cached, it MUST expire no later than 60 seconds after the RS sent the introspection request that validated the token. It MUST also expire no later than the access token or grant expiration when present. The AS MUST include `exp` in every positive introspection response for an expiring PDPP token. A signed URL may remain usable after grant revocation until it expires; its lifetime is bounded by the preceding rule. Redirect URLs may be valid for less than 60 seconds; clients cannot rely on the former 60-second minimum. @@ -1567,8 +2155,9 @@ This makes a future error code safe to introduce: an older client keeps handling | `grant_expired` | 401 | `authentication_error` | Token is inactive because its grant has expired, and authenticated context establishes this cause. See Inactive tokens below. | | `grant_revoked` | 401 | `authentication_error` | Token is inactive because its grant has been revoked, and authenticated context establishes this cause. See Inactive tokens below. | | `grant_invalid` | 403 | `permission_error` | Resolved grant is malformed or cannot be served without changing its authorization meaning. | +| `disclosure_unavailable` | 403 | `permission_error` | The RS cannot safely serve the authorized projection and will not add unauthorized fields. | | `blob_not_found` | 404 | `not_found_error` | `blob_id` is unknown or stale, or no record the token may read references it. | -| `not_found` | 404 | `not_found_error` | Stream or record not found. | +| `not_found` | 404 | `not_found_error` | Stream, instance, or record not found. | | `cursor_expired` | 410 | `gone_error` | `changes_since` token is too old; start again from `beginning`. | | `rate_limit_exceeded` | 429 | `rate_limit_error` | Too many requests. Includes `Retry-After` header. | | `api_error` | 500 | `api_error` | Internal server error. | @@ -1600,7 +2189,7 @@ Conformance is role- and behavior-based. A conformant implementation is not requ A conformant authorization server: 1. Accepts selection requests using the RFC 9396 `authorization_details` envelope with `type: "https://pdpp.dev/data-access"`. -2. Validates selection requests against one retained SourceDeclaration snapshot: rejects unknown streams, unsupported selection parameters (e.g., `time_range` on a stream without `consent_time_field`), and unrecognized selection presets. +2. Validates public request structure and owner-independent capabilities, rejecting public invalidity with `invalid_authorization_details`. Resolves selections against one retained SourceDeclaration snapshot. Treats an otherwise valid selection that is infeasible under privately accepted capabilities as owner-dependent eligibility, only within authenticated review. There, omits an optional unapproved stream or refuses under the required-stream/minimum rules with indistinguishable `access_denied`, without client-visible private diagnostics, as [Authorization privacy boundary](#authorization-privacy) requires. 3. Issues grants that conform to the grant schema defined in Section 7 (normative field tables). The AS generates `grant_id` and `issued_at`; it resolves other grant fields from authenticated identities, the selection request, the accepted source declaration, eligible instance handles, user approval, AS policy, or AS-resolved client metadata. 4. Expands wildcards and selection presets into explicit stream names, fields, per-stream instance handles, resources, and frozen time constraints before issuing the grant. 5. Produces a binding-neutral Source validation failure when a request contains both or neither of `streams` and `selection_preset`. The OAuth/RAR binding maps it to RFC 9396 `invalid_authorization_details`. @@ -1608,28 +2197,51 @@ A conformant authorization server: 7. Renders requester identity metadata, declaration-authored data descriptions, structured policy declarations, and client-authored claims as semantically distinct categories during consent. MUST attribute `client_claims` to the client and MUST NOT present them as protocol-enforced terms. If `client_claims` are rendered during final review, binds the normalized exact claims into the immutable final approval artifact and review revision, and preserves that binding in retained consent evidence, without adding them to the resolved grant or RS enforcement. Records in the issued grant's `client.client_display` the exact `policy_uri` and `tos_uri` it presented during consent, and omits any it did not present. 8. Tracks grant lifecycle (active, expired, revoked). Reflects revocation immediately in introspection: the revoked grant is inactive at once, and a token is `active: false` when no grant it covers is active. 9. Issues access tokens bound to specific grants. Access tokens include the PDPP introspection extension fields. -10. For `single_use` grants, consumes the grant atomically with first client-token issuance. Gives that access token a finite expiration set by local policy and, when the grant has `expires_at`, no later than `expires_at`; that expiry ends the grant's one read window. Lets a later token in the same refresh-token family carry the grant only inside the window, reports the grant inactive after it, and otherwise rejects issuance against the consumed grant. -11. Validates stream/field/view/resource-id shape at grant issuance. +10. For `single_use` grants, consumes the grant atomically with first client-token issuance. Gives that access token a finite expiration set by local policy and, when the grant has `expires_at`, no later than `expires_at`; that expiry ends the grant's one read window. Lets a later token in the same refresh-token family carry the grant only inside the window, reports the grant inactive for reads after it, and otherwise rejects access-token issuance against the consumed grant. +11. Validates stream/field/view/resource-id shape at grant issuance. Rejects `resources` on a stream with more than one instance. 12. MUST NOT define a view including fields absent from the retained SourceDeclaration schema. 13. Resolves view names to field lists at issuance time; stores resolved `fields` in the `StreamGrant`. Client-token record reads reject query-time `view` in v0.1. Owner-token current-capability reads MAY resolve current views. -14. Obtains explicit affirmative user consent before issuing grants with `purpose_code: "https://pdpp.dev/purpose/ai_training"`. Never presents an `ai_training` detail as selected by default. In a request with several details, lets the owner approve any other detail while declining it. +14. Rejects a detail whose `processing_permissions` is malformed or contains a duplicate, unknown, or unsupported value, with `invalid_authorization_details`, and never ignores, substitutes, or narrows such a value or issues an ordinary grant in its place. Advertises in `pdpp_processing_permissions_supported`, and grants, only permissions whose complete defining contract it implements. Treats `https://pdpp.dev/processing/ai_training` as unsupported until the PDPP AI Training Profile is published and its registration is approved, and afterwards supports it only by conforming to that profile. 15. Resolves omitted instance IDs before the final approval surface. Binds exact resolved instances and all final decision fields to an immutable review revision or digest. Rejects stale approval if eligibility or the reviewed revision changes before approval. 16. Retains one exact SourceDeclaration snapshot through request validation, consent display, narrowing, issuance, and consent evidence. A later current declaration never substitutes for it. 17. Returns 400 `unsupported_version` if `PDPP-Version` header specifies an unsupported version. -18. For a separated AS and RS, authenticates the RS at the RFC 7662 introspection endpoint and returns the complete grant enforcement context in one response. +18. For a separated AS and RS, authenticates the RS at the RFC 7662 introspection endpoint and returns the complete grant enforcement context in one response, including `pdpp_instance_bindings`. Never returns `pdpp_instance_bindings` to a client. 19. Consumes each OAuth authorization code atomically on its first successful redemption. Rejects every later redemption with `invalid_grant` and does not issue another token. 20. Issues a refresh token only when at least one grant the token response covers is `continuous`, and never extends a `single_use` grant's read window through refresh. It rotates refresh tokens by family. Reuse of a superseded token revokes the family and every family-linked access token, returns `invalid_grant`, and requires fresh authorization. 21. Rejects unsupported persisted authorization state before introspection or request handling. Does not reconstruct missing facts from current configuration and requires fresh consent when no migration applies. 22. Rejects a source declaration containing an unrecognized `source.kind` or `streams[].semantics` value. 23. Issues a grant with `grantors` only after each listed representative approves the same immutable final review revision. Authenticates and verifies each representative before accepting approval, binds each identity and capacity to that revision and retained consent evidence, and keeps the data subject in `subject`. 24. Lets the owner approve or decline each detail of a request on its own. Issues one grant for each approved, resolved detail, covering one subject, one source, and one purpose, with its own lifecycle. Identifies grants by `grant_id` and does not treat subject, source, and purpose as a grant key. -25. If it offers client-initiated revocation, ends grants as Section 10 defines: revoking a refresh token, current or superseded, ends every grant its family covers; revoking an access token ends its grants only when no refresh-token family covers them. In the OAuth binding, implements it as RFC 7009 token revocation and advertises `revocation_endpoint` in RFC 8414 metadata. +25. If it offers client-initiated revocation, ends grants as Section 10 defines: revoking a refresh token, current or superseded, ends every grant its family covers; revoking an access token ends its grants only when no refresh-token family covers them. In the OAuth binding, implements it as RFC 7009 token revocation and advertises `revocation_endpoint` in RFC 8414 metadata. Accepts `pdpp_disposition` on that request and records it only when the request carries current client authentication. 26. Ends one grant among several that share a credential without revoking that credential or ending the other grants. -27. Rejects a declaration that names an ineligible `consent_time_field` or a non-boolean `consent_time_content_may_exceed`. Rejects a `time_range` with no bound, a bound whose type does not match the field's format, an invalid bound, or a `since` not before `until`; the OAuth/RAR binding returns `invalid_authorization_details`. Never converts or rounds a bound. Sets `time_constraint.type` from the field's format in the retained declaration. +27. Rejects a declaration that names an ineligible `consent_time_field` or a non-boolean `consent_time_content_may_exceed`. Rejects a `time_range` with no bound, a bound whose type does not match the field's format, an invalid bound, or a `since` not before `until`; the OAuth/RAR binding returns `invalid_authorization_details`. This error applies only to public invalidity. A failure that depends on a declaration accepted privately for the owner is an eligibility failure under [Authorization privacy boundary](#authorization-privacy) and MUST NOT produce a client-visible declaration-dependent validation error. Never converts or rounds a bound. Sets `time_constraint.type` from the field's format in the retained declaration. 28. For each time-bounded stream, renders the exact bounds with their inclusive and exclusive meaning and the declared meaning of the field. Shows a relative label only when it has verified it for those bounds. Discloses that matched records can contain data from outside the bounds when the stream declares `consent_time_content_may_exceed: true`. For a `continuous` grant, discloses that the client can see records leave the window. +29. Gives each client pairwise identifiers: `subject.id`, `grantors[].id`, instance handles, and any ID Token `sub` differ between clients for the same subject, grantor, or instance. They stay the same for one client, are never reassigned, and cannot be reversed by a client. Sets ID Token `sub` to the authenticated person's identifier, which is a grantor's identifier when a representative authenticates. Uses a globally resolvable `subject.id` only when the owner explicitly chooses to disclose it to that client, and binds that identifier and the client into the final approval artifact and retained consent evidence. Returns an internal subject identifier and `pdpp_instance_bindings` only to the RS. +30. Resolves each request as [Request resolution](#request-resolution) defines before final approval. Treats requested instances, resources, time bounds, and the field ceiling as upper limits, never narrows below schema-required fields, and adds nothing to compensate for a refused selection. Checks required streams and each retained stream's `minimum` before issuing a grant or client token. Reports an unmet minimum on a required stream as `access_denied` and a malformed `minimum` as `invalid_authorization_details`. +31. Resolves purpose and retention only from the current request or recipient-authorized standing terms, and retains the evidence identifying those terms with the consent evidence. Rejects a `retention.max_duration` that is not in the form `PnD`. Discloses during owner review that envelope identifiers are part of every disclosed record. +32. Returns one `{ type, grant }` element per covered grant in every token response that issues a client access token, including refresh responses, as [Client-visible authorization result](#authorization-result) defines. Returns the same element shape in introspection. +33. Advertises `https://pdpp.dev/data-access` and `https://pdpp.dev/grant-lifecycle` in `authorization_details_types_supported` and rejects unknown detail types, and a detail that carries a member it does not define. +36. For a detail that carries a processing permission, requires a distinct affirmative owner selection, never preselects it, and never makes another detail depend on it. Renders each permission as a labeled term distinct from the purpose. Requires a non-empty `purpose_description` on an AI training detail. Issues the grant with its exact permission set or not at all, and never adds a permission to a detail that did not request it. Binds that set into final owner review, the review revision, retained consent evidence, the grant, token results, and introspection, and requires a new review when the set changes after review. Includes a reviewed `expires_at` in every training grant. On the approval surface for an AI training detail, makes the statements and avoids the claims that [AI training consent](#ai-training-consent) lists. +37. When it supports a processing permission, keeps read access and processing authority distinct as [Read access and processing authority](#processing-authority) defines. Issues no further processing authority after grant revocation or grant expiry. When the grant has `expires_at`, issues no processing authority that outlasts it. Never lets a processing credential confer read access. Does not treat read-window closure, access-token expiry, or refresh-token replay detection alone as ending processing authority or prohibiting its renewal. +38. Its operator does not use owner data held in the AS role for AI training, except under a training grant issued to it as a client. +39. Provides the grant lifecycle operation and advertises `pdpp_grant_lifecycle_endpoint`, as [Grant lifecycle operation](#grant-lifecycle) defines. For queries, accepts any token it issued to the client that covers the grant, whether active, expired, superseded, or revoked. Requires current client authentication for writes. Returns indistinguishable `invalid_grant` entries for unknown, foreign, and uncovered grants. Stores token digests, not tokens, and can disable any token it issued for lifecycle use. Admits at least one query per grant per retry interval from each client. Records a client-conveyed `delete` as that client's `received` report only when the request reports the client's first receipt time. +40. Returns a positive assessment only when no erasure instruction applies to the grant, whatever its read state, and only from state ordered after every terminal event it has acknowledged. +41. On every interface through which the owner ends a grant, requires an explicit disposition for each grant in the action's scope, rejects a request without one, and applies no default. Presents `keep` and `delete` with neither preselected, and lists the complete affected set as [Ending paths](#ending-paths) defines, including already-ended and consumed grants whose held data may remain and grants that carry a processing permission. +42. Records each erasure instruction durably before acknowledging it and preserves its terminal effect. An immediate instruction revokes an active grant. An advance instruction takes effect at grant end and does not itself end the grant earlier. Records acceptance, first return, reported receipt, and reported completion or exception separately. Accepts `retained_until` only in its three forms, and shows a `retained` report's end in that form, never as completed deletion. From the effective time, issues no further processing authority that permits use of the covered data. +43. Shows the owner the stop-use and deletion statements that [Erasure](#erasure) requires, and the time by which covered processing stops. Never shows a receipt-based deletion deadline calculated from acceptance or first return. Until a receipt is reported, shows the latest recorded stage and no deletion date. +44. Meets [Lifecycle durability](#lifecycle-durability): records terminal events before acknowledging them, in a history that no restore or failover through a path its mechanism detects can make an enforcement point treat as current while it omits an acknowledged terminal event. Records the other events that section lists before a response discloses or relies on them, and never reuses a `grant_id` or `instruction_id`. Never returns a positive assessment, an active introspection result, or a token that contradicts an acknowledged terminal event, on any issuance or assessment path, including code, device-code, and refresh exchanges, token re-delivery, lifecycle write authentication, and package fan-out. This holds except after a restore or rollback path that it discloses as undetected. After restore or failover, treats a history as current only when its declared mechanism establishes that the history includes every acknowledged terminal event, and otherwise fails closed. Describes the durability it actually provides, including the disk and host losses it does not survive, the restore and rollback paths its mechanism does not detect, and what such a path can revive. While its history is unavailable, accepts, records, and later applies owner revocations, dispositions, and erasure requests. For an action affecting several grants, records a result per grant and reports the action complete only when every requested ending and disposition is recorded. Keeps lifecycle and authentication bindings for as long as that section requires. +45. Shows in final owner review what happens to held data after the grant ends, as [Recipient commitments and approval](#recipient-commitments) defines. +46. On security revocation, shows the owner the ending and its reason and offers the disposition. Before decommission, offers a disposition for every grant whose held data may remain, shows the stage of each disposition, and warns about each `delete` that no client has received. In a narrowing flow, states the effect of each disposition as [Grant narrowing](#grant-narrowing) defines. Lets the owner request erasure for an ended grant while its held data may remain. +47. Supports [lifecycle recovery](#lifecycle-recovery), and gives a recovery token no read access and no refresh token. +52. Applies [Authorization privacy boundary](#authorization-privacy) to every supported authorization entry point. Performs owner-independent syntax and binding checks without querying private owner availability. Defers owner-dependent resolution to authenticated review. +53. Keeps optional ineligible streams unapproved. Refuses required ineligible streams and unmet required authorization minima with `access_denied`. Preserves `invalid_authorization_details` for malformed or unsupported details and any error defined for a specific authorization-details type. +54. Demonstrates equivalent pre-authentication observables when only protected owner state varies. Demonstrates equivalent client-visible eligibility denials after review. Includes status, response shape and size, redirects, headers, transaction behavior, and timing in its evidence. +55. Records the entry points, protected-state variants, timing method, and observation limits exercised by its authorization-privacy tests. Reports an unobserved supported path as UNVERIFIED rather than passed. +56. States during final owner review that ordinary access confers no independent-recipient disclosure authority. Distinguishes parties acting for the client. Does not claim that this duty technically prevents onward disclosure. Applies the closed processing-permission rules without substitution or fallback. +57. Passes a differential authorization-privacy case that varies private declaration acceptance, temporal capability, and view availability against a matched owner refusal. The client-visible result, the callback, and any transaction-status channel are equivalent across the variants, and no unapproved diagnostic reaches the client. ### Resource Server conformance @@ -1647,17 +2259,23 @@ A conformant Core RS: `invalid_request` before consulting current declaration metadata; owner-token current-capability reads MAY retain declared filter behavior. 10. Rejects unknown query parameters and unsupported query shapes with 400 instead of silently ignoring them. 11. Implements the `PDPP-Version` header negotiation. -12. Scopes owner token access to a single subject's data store; derives `subject_id` from introspection response. +12. Scopes owner token access to a single subject's data store; derives `subject_id` from introspection response. Never discloses the introspection `subject_id` to a client. 13. SHOULD support owner-authenticated access to the `/v1/streams/{stream}/records` query endpoints without a client grant, allowing the data subject to export their own data directly (self-export). 14. For owner-token stream-metadata reads, returns the full current stream metadata within the owner's subject/source/connection scope, including current query, view, and relationship capabilities. 15. For client-token stream-metadata reads, returns only a projection derived from the resolved authorization context: the granted stream and its explicitly granted fields, and immutable/frozen grant facts. MUST NOT include current view, relationship, filter, expansion, or aggregation capability unless that capability is explicitly part of a future frozen grant vocabulary, and MUST NOT surface a source-declaration change made after grant issuance. -16. Publishes RFC 9728 protected resource metadata at the location RFC 9728 Section 3 derives from its resource identifier, carrying `resource`, the four `pdpp_`-prefixed members defined in Section 8, and `authorization_servers` when its issuer set is enumerable. Returns a `WWW-Authenticate: Bearer` challenge on 401 per RFC 6750 Section 3, carrying the RFC 9728 `resource_metadata` parameter. +16. Publishes RFC 9728 protected resource metadata at the location RFC 9728 Section 3 derives from its resource identifier, carrying `resource`, the four required `pdpp_`-prefixed members defined in Section 8, and `authorization_servers` when its issuer set is enumerable. Also carries `pdpp_freshness_granularity_seconds` when it attaches `freshness` to client-token responses. Returns a `WWW-Authenticate: Bearer` challenge on 401 per RFC 6750 Section 3, carrying the RFC 9728 `resource_metadata` parameter. 17. Does not interpret an unrecognized stream semantic as `append_only` or `mutable_state`, or an unrecognized grant `source.kind` as a known provenance class. -18. Serves a blob only when a record the requesting token may currently read, including its field projection, references it. Otherwise returns 404 `blob_not_found`. Gives a redirect's signed URL an expiry no later than the positive-status cache expiry, or 60 seconds after token validation when no result was cached, and no later than the token or grant expiration when present. +18. Serves a blob only when a record the requesting token may currently read, including its field projection, references it. Otherwise returns 404 `blob_not_found`. Gives a redirect's signed URL an expiry no later than the positive-status cache expiry, or, when no result was cached, 60 seconds after the RS sent the introspection request that validated the token. The expiry is also no later than the token or grant expiration when present. A delayed response never restarts this deadline. 19. Returns 401 with `WWW-Authenticate: Bearer error="invalid_token"` for every inactive access token. Uses the structured code `grant_expired` or `grant_revoked` only when authenticated context establishes that cause, otherwise `authentication_error`. 20. Emits a tombstone for each record visible at the previous horizon and not visible at the new one, and for no other record. Retains the state needed to determine visibility at every unexpired horizon, and otherwise fails the session with 410 `cursor_expired`. Uses the exact client tombstone shape for client tokens. For owner tokens, adds `removal`, and `deleted_at` and `emitted_at` only for a deletion. -21. Binds each page cursor and `changes_since` token to its grant, or owner subject and scope, and to its query context, and rejects a mismatch as `invalid_cursor`. Orders a `changes_since` session by canonical key string, does not serve a record deleted after the session's first page, and rejects `expand[]` and `expand_limit[...]` on `changes_since`. Issues tokens and page cursors that reveal no readable position, time, or field value, and whose equality or ordering signals no change outside the grant or owner scope. +21. Binds each page cursor and `changes_since` token to its grant, or owner subject and scope, and to its query context, and rejects a mismatch as `invalid_cursor`. Orders a `changes_since` session by `instance_id` and then canonical key string, does not serve a record deleted after the session's first page, and rejects `expand[]` and `expand_limit[...]` on `changes_since`. Issues tokens and page cursors that reveal no readable position, time, or field value, and whose equality or ordering signals no change outside the grant or owner scope. 22. Compares time values and bounds by the grant's frozen `time_constraint.type`, never a current declaration, as calendar dates or exact instants, without a host, viewer, or owner time zone. Validates values itself under RFC 3339, including its leap-second rule. Excludes a record whose value is absent, null, or invalid from every read surface. Applies the same rules to owner-token range filters on `date` and `date-time` fields, using the declared format. +23. Puts `instance_id` on every record and tombstone it serves: the grant's handle for a client token, and the owner's handle for an owner token. Serves each `resource_ref` in the resolved or redacted form according to the token-kind, source, and sync-horizon rules in Section 4. In the next session, returns each referring record that the previous session served with a reference redacted after a target deletion, as Section 4 requires. Identifies records within a stream by instance and canonical key in sync, removals, cursors, and single-record reads. Requires `instance_id` on a single-record read or record delete when the query context covers more than one instance of the stream, and on every blob fetch. Rejects a missing one with 400 `invalid_request`. +24. In a separated deployment, resolves every handle through `pdpp_instance_bindings`. Fails a client request with 403 `grant_invalid` when a handle the request needs has no binding or names no stored instance. Treats an owner instance without a binding as outside the owner scope. +25. When it attaches `freshness`, lists exactly one entry for each instance that the query context authorizes for the stream, whatever the page contains. Computes `last_success_at` over the full authorized scope of the query, counts only successful operations as Section 8 defines them, and reports null when it cannot establish relevance safely. In a client-token response, carries no failure time, truncates each value to its declared granularity of at least 3600 seconds, and reports no value before its interval ends. Takes a snapshot of the array on the first page of a `changes_since` session and repeats that exact snapshot on every later page. Reports no staleness verdict. +26. Builds disclosed `data` only from the top-level members the grant and the request-time field selection permit, with no nulls or fabricated values for withheld members. Refuses a read it cannot serve that way with 403 `disclosure_unavailable`. +27. Enforces the resolved grant independently of provider action permission, as [Existing permissions and action results](#existing-permissions) defines. Never treats a data grant as action permission or lets a broad read scope widen a grant, and discloses existing data in an action response only under the applicable data grant. +29. Never treats `processing_permissions` or a processing credential as read authority. Its operator does not use owner data it holds in the RS role for AI training, except under a training grant issued to it as a client. Collection resource servers, connector runtimes, and connectors make no separate conformance claim in v0.1. A connector conforms to PDPP as Section 1 states: by producing a source declaration valid under Section 5 and serving its data through a resource server conforming to Section 8. The informative [PDPP Collection Profile](spec-collection-profile) describes runtime behavior and defines no conformance requirement. @@ -1670,11 +2288,87 @@ A conformant client: 3. Treats `cursor` and `changes_since` tokens as opaque and from distinct token spaces. MUST NOT use a `next_cursor` value as a `changes_since` parameter. 4. Stores `next_changes_since` from the terminal page of a `changes_since` response for use in the next sync session. 5. Respects HTTP 410 `cursor_expired` responses by starting again from `beginning`, rather than retrying with the expired token. After every completed `beginning` session, replaces its copy of the stream with that session's result. -6. Honors retention commitments declared in the grant. +6. Honors retention commitments declared in the grant. Counts each record's retention ceiling from its first acquisition, never restarts it, and applies `on_expiry` at the ceiling to the record and its derivatives with no grace period. 7. Treats unrecognized error codes as opaque, falling back to the exact HTTP status code and applicable response headers rather than failing on an unknown code. Takes the actual status code and headers as the authoritative outcome. Uses a recognized `error.type` only to refine category or presentation, and only when compatible with that outcome. Ignores an absent, unrecognized, or status-incompatible `type` for control flow, and never fails to parse on an unknown `code` or `type`. 8. Where local policy depends on source provenance, MUST read `source.kind` from the issued grant and apply that policy before first use of the records. A client MUST NOT assume a provenance class it did not read from the grant, and MUST NOT treat an unrecognized `source.kind` as either known value. A client with no provenance-dependent policy has nothing to check. -9. Stops using an access token on a 401 with Bearer error `invalid_token`, and stops requests against a grant on `grant_revoked`. Does not treat an inactive token as proof of revocation. -10. Treats a tombstone for an ID it does not hold as a no-op. Reconciles records it obtained outside sync sessions itself, because the sync guarantee covers only a copy built from sync sessions. +9. Stops using an access token on a 401 with Bearer error `invalid_token`, and stops requests against a grant on `grant_revoked`. Does not treat an inactive token as proof of revocation. Starts a grant lifecycle query before further use of held data of that grant. +10. Identifies each record within a stream by its `instance_id` and `id` together. Treats a tombstone for a record it does not hold as a no-op. Reconciles records it obtained outside sync sessions itself, because the sync guarantee covers only a copy built from sync sessions. +11. Does not infer from an empty result, the end of pagination, a tombstone, or a 404 that a record does not exist at the source or that collection is complete. Treats a null `last_success_at` only as the absence of a reportable timestamp. +12. Establishes that the AS advertises `https://pdpp.dev/data-access` before requesting it. +13. Inspects the authorization result in each token response, including refresh responses, before requesting record disclosure, and requests no disclosure when it cannot obtain or interpret the result. Does not infer authorization from its original request, a tool listing, or token syntax. +14. Does not validate a projected `data` object as a full stream record. +17. Trains on PDPP inputs only when every contributing PDPP input has covering training permission and valid processing authority, as [AI training](#ai-training) defines, regardless of purpose code or acquisition grant. Applies this rule to derivatives and imposes it on every recipient or subprocessor receiving PDPP inputs. Treats the legacy purpose code `https://pdpp.dev/purpose/ai_training` as conferring no training authority. +18. Requests a processing permission only when the AS advertises it in `pdpp_processing_permissions_supported`, in a detail separate from any ordinary access, and with a `purpose_description` where Section 6 requires one. +19. After a grant ends, uses its held data only within the grant's surviving-use terms, including only the limited continuation of already-issued processing authority permitted by the defining profile. Otherwise keeps, but does not use, data held only under a grant that carries a processing permission. +20. Holds a positive assessment before first use of a grant's held data. Never treats record delivery, introspection, a read error, or a package read status as an assessment. +21. While it runs and it or a party acting for it holds held data of a grant, attempts a lifecycle query at least once per reconciliation interval, starting one interval after first acquisition. Retries failed or unanswered attempts as [Positive assessment and reconciliation](#reconciliation) requires, including its `Retry-After` and transport-failure widening rules, until an attempt succeeds or it holds no held data of the grant. Also starts a query before further use after a failure that shows the grant may have ended, and after resuming from suspension or power-off if an attempt fell due meanwhile. Does not treat a failed or unanswered query as a reason to stop use the grant's terms permit. +22. On learning of an erasure instruction, stops use as soon as practicable and no later than the stop-use bound after its effective time, or at once if it learns of the instruction after that deadline. Deletes the covered data, with the scope and by the deadline [Erasure](#erasure) defines. Records its first receipt, never restarts a deadline, and treats the instruction as terminal. +23. Applies the overdue-disposal rules in [Erasure](#erasure) before further use. Treats backups and legally retained data as [Erasure](#erasure) defines. +24. Imposes the held-data duties on every party acting for it, and relays erasure instructions with absolute deadlines to it, as [Downstream holders](#downstream-holders) defines. +25. If it offers its own disconnect, states what happens to held data and offers `keep` and `delete` with neither preselected. Treats `delete` as an erasure instruction effective at once. +26. Keeps the records that [Erasure](#erasure) requires. Exercises already-issued processing authority after effective erasure only within that section's limited continuation and the defining profile's stop requirements. +28. Retains the authenticated AS issuer with every grant and does not infer it from `grant_id`, `source.id`, or an untrusted credential, as Section 8 requires. +29. Discloses PDPP data to an independent recipient only under an expressly covering registered processing permission and valid authority under its defining profile, except for the required-by-law case in Section 7. +30. Classifies a receiving party by the operation it performs. Does not treat independent use as processing for the client. Applies the rule to derivatives and service outputs as well as source records. +31. Does not infer independent-recipient disclosure authority from purpose, an owner action instruction, a claim, a positive assessment, an erasure exception, or read-token activity. Records any required-by-law disclosure as Section 7 requires. + +### Held-data conformance cases {#held-data-cases} + +Each case below is a conformance requirement on the roles it names, stated as the outcome a test observes. A test controls the clocks of the AS and the client. Cases P1 to P9 cover each [ending path](#ending-paths). Cases C1 to C9 cover each [time limit](#held-data-limits), clock, and the legal-retention exception. Identifiers C3 and C5 are not used. Cases D1 to D5 cover durability and authentication. + +A conformance report MUST classify each assertion as protocol-visible or adapter-observed. Client use, retention, erasure, lineage, and backup assertions require a declared deployment adapter identifying the tested operation and storage surfaces. Without the required observation, the report MUST mark the assertion UNVERIFIED, never passed. Erasure reports alone are not evidence of deletion. + +Owner actions and displays, security revocation, decommission, downstream relay, and restore or history-loss setup use declared deployment adapters. Core defines no universal HTTP endpoint or UI locator for these controls. The report MUST identify the exercised storage failure domains. Tests MUST run mandatory subcases and subcases for each supported capability. An unsupported optional capability MUST be reported as not applicable, with claim or metadata evidence, never passed. This rule also applies to processing subcases until the defining profile is registered and supported. + +Unless a variant states otherwise, fixtures exclude learned parameters, pre-effective non-identifiable data, independent acquisitions, and legal retention. Other deadlines fall after the tested deadline. Cross-limit variants MUST verify the earliest applicable deadline, with isolated legal-retention and independent-acquisition controls. A reported exception is not completed deletion. An anonymization assertion identifies the client's stated non-identifiability test and its observed result; it does not establish universal anonymity. + +| Case | Setup | Required outcome | +|---|---|---| +| P1. Owner withdrawal at the AS | A client holds data under an active `continuous` grant and a consumed `single_use` grant. The owner disconnects the client at the AS. | The AS lists both grants and presents `keep` and `delete` with neither preselected. It rejects a programmatic request that lacks a disposition. Lifecycle answers report `revoked`, with `held_data` matching each recorded disposition. A `keep` grant answers `permitted`. In a variant, the owner later requests erasure of the `keep` grant: the AS records a new instruction and the answer becomes `erase`. | +| P1a. Package with an ended child | A package has child A, revoked earlier with `keep`, and active child B. The client disconnects the package with `pdpp_disposition=delete` and current client authentication. | A and B both answer `erase`; A's `read_state` and `ended_at` remain unchanged. In a variant, the AS records B's instruction but not A's: it returns HTTP 503 with A `pending` and B `recorded`, and does not report the action complete. A retry records A and leaves B's instruction clocks unchanged. | +| P2. One package child | A package has children A and B. The owner withdraws A with `delete`. | A answers `erase`. B still reads, and its answer is `permitted`. The client deletes A's data, and deletes or regenerates without A's data every derivative that mixes A and B. | +| P3. Narrowing | The owner revokes grant G with `delete` and approves a narrower grant G2. | Before the final step, the AS states the effect of each disposition. G answers `erase`, and the client deletes its G copy. If the client reacquires data, the acquisition uses G2 within G2's scope. Relabeling an old G acquisition never evades its instruction. Choosing not to reacquire does not fail this case. | +| P4. Revocation at the owner's direction | The owner chooses `delete` in the client while the AS is unreachable. Later the client revokes its refresh-token family with `pdpp_disposition=delete` and the current refresh token. | The client's stop-use and deletion clocks start at the owner's choice, not at AS acceptance. Each grant the family covers then answers `erase`. With a reported owner-choice time, the AS records that time as receipt despite delayed request delivery. Without it, the AS records no receipt-based date and shows no deletion date. In a variant, a public client presents only a superseded refresh token, with no other current client authentication: the grants end and no disposition is recorded. A confidential client with valid current authentication records `delete` even when the target token is superseded. In a variant, the AS crashes after it durably retains the request and before it completes the request's effects. A retry of the same request, with no replacement credential, completes the revocation and the disposition without new owner approval and without restarting any clock. For each request that carried current client authentication, including the original request in a crash-and-retry variant, the AS records the family revocation with the disposition. | +| P5. Token revocation without a disposition | The client revokes its refresh-token family without `pdpp_disposition`. | The grants end and answer `revoked` with `held_data` `permitted`. No erasure instruction exists. Revoking an access token that a family covers ends only that token. In a variant, revoking an access token that no family covers ends its grants, which answer `revoked` with `held_data` `permitted`. | +| P6. Expiry | A grant reaches `expires_at`. In a variant, the owner elected deletion in advance. | Reads end, and no processing authority outlasts `expires_at`. The answer is `expired` and `permitted`. In the variant, the answer is `erase` with `effective_at` equal to `expires_at`. | +| P7. Security revocation | The AS ends a grant because the client is compromised. | No erasure instruction exists, and the answer is `permitted`. The owner surface shows the ending and its reason and offers the disposition. Choosing `delete` makes the answer `erase`. | +| P8. Refresh replay | The client reuses a superseded refresh token. | The family's tokens are revoked. The grant does not end and no erasure instruction exists. The superseded token still authenticates a lifecycle query. | +| P9. AS decommission | The owner retires the AS. One grant has a `delete` that the client has not received. | The AS first offers a disposition for every grant whose held data may remain. It shows each disposition as offered, recorded, sent, or receipt reported, and warns that the undelivered `delete` cannot reach the client once the AS stops answering. | +| C1. Reconciliation interval | A client first acquires data at t0 and keeps it. The AS is unreachable. The client runs continuously unless a variant says otherwise. | The client attempts a query by t0 plus the reconciliation interval, and at least once per interval afterwards. While no held data remains, no attempt is required. In a variant, the client clears all held data before the first attempt falls due, then acquires data again under the same grant. Attempts resume, and the client starts a query before further use once a reconciliation interval has passed. Voluntary lifecycle queries do not fail this case. | +| C1a. Retry after a failed attempt | The AS is unreachable for 1 hour, twice, 24 hours apart; each outage covers a scheduled attempt. In a variant, a request remains unanswered beyond the retry interval and no `Retry-After` has been received. The client runs continuously unless a variant says otherwise. | After each failed attempt, the client attempts again within the retry interval until an attempt succeeds, subject to the stated `Retry-After` and transport-failure widening rules. In a variant, the AS is unreachable at the transport level for 3 days: after one reconciliation interval of failed attempts, attempts at least once per reconciliation interval pass the case. The AS admits at least one query per grant per retry interval; other queries MAY receive HTTP 429, which counts as a failed attempt. In the unanswered-request variant, the next attempt starts within the retry interval of the preceding attempt's start, without waiting for that request to finish. In a suspension variant, the client powers off after a failed attempt: it makes no attempts while off and starts a query before any use on resume; a failed or unanswered query does not stop use the grant's terms permit. | +| C2. Stop-use bound | An erasure instruction takes effect at w. The client receives it at q no later than w plus the stop-use bound. | The client stops use as soon as practicable after authenticated receipt; starting or scheduling cancellation alone does not stop use. The adapter identifies the fixture's use surfaces and a practicable cessation point, and observes that no queued, in-flight, or new use continues past that point. Adapter observations record receipt, cancellation, and completion times on the declared test clock. No queued or in-flight use occurs after the earliest applicable deadline, including w plus the stop-use bound. In a variant with later receipt, it stops at once on receipt. In a variant where the AS is unreachable from w until after w plus the stop-use bound, the client stops at once on receipt; the test does not require it to stop before receipt. The test adds no grace period. | +| C4. Deletion bound | The client first receives an erasure instruction at q. The AS redelivers it the next day. | Deletion is complete by q plus the deletion bound. Redelivery does not move the deadline. If the client sends a `received` report, it gives q. The AS shows no receipt-based deletion date before such a report. | +| C5a. Clock discontinuity | The client has received an erasure instruction, or holds a record whose retention ceiling is pending. The client's wall clock then moves backwards, the process restarts from older state, or its elapsed-time clock omits a suspension. | No use or disposal deadline moves later. The client establishes conservative elapsed time or stops use until it can; it completes due disposal before further use. | +| C6. Retention ceiling | A record is first acquired at a, then reread and transformed. `on_expiry` is `anonymize`. | The client applies `on_expiry` to the record and its derivatives by a plus `max_duration`. An erasure instruction before that time requires deletion instead. In a variant, the client disposed of the raw record but kept a derivative; a later erasure instruction covers that derivative. In a variant, the client removes names but keeps a per-owner hash: this does not pass as anonymization. | +| C7. Processing cessation | Not applicable until a processing permission's defining profile is published and supported; a test reports it as not applicable, never as passed. The test runs once for each supported permission. An erasure instruction covers data that another grant of the same client, carrying the permission, also covers. | From the instruction's effective time, the AS issues no processing authority that permits use of the covered data. Authority already issued ends within the cessation bound of the permission's registered defining profile and version. The test reads that bound from the registration, not from this case. The [registration test](#processing-permissions) caps it at 1 hour. The owner sees the stop time. | +| C8. Downstream holders and backups | The client relays an erasure instruction to a party acting for it, and holds a backup of covered data. | The party receives the client's deadlines as absolute times. Its copies and the backup are deleted, or made irrecoverable, by the client's deadlines. A restore replays deletion state before any restored data becomes usable. The adapter enumerates tested backup stores, keys, and recovery paths. Key destruction meets the assertion only when covered data is irrecoverable through those paths; unobserved paths are reported UNVERIFIED. | +| C9. Legal retention | An erasure instruction covers data that includes invoices that tax law requires the client to keep until an audit closes. The audit's close date is not known. | The client deletes the other covered data by the deletion bound. It processes the invoices only as the obligation requires. A `retained` report carries `retained_until` as `event:` text, with basis and scope. The AS shows that end as an event, never as completed deletion. A later report with a date-time end corrects the earlier one without overwriting it. The AS rejects a `retained_until` in none of the three forms, and a date-time earlier than `reported_at`. In a variant, the client reports `unknown`. When the obligation ends, the client deletes the invoices and reports `completed`. | +| D1. Restore safety | The AS acknowledges an erasure instruction, then restores a backup taken before it, or answers from a stale replica. | No positive assessment, active introspection result, or token contradicts the acknowledged instruction. The lifecycle operation returns `temporarily_unavailable` rather than a stale positive answer. A stale replica MAY return the instruction. In a variant, a stale replica holds an advance election for grant G. The owner then requests immediate erasure at the authoritative AS. Queried after the originally scheduled time, the replica returns the authoritative effective instruction or `temporarily_unavailable`, never the old `effective_at` or `stop_use_by`. | +| D1a. Restore across issuance paths | The AS acknowledges revocation of grant G, then restores its main store from a backup in which G and its tokens are live. In a variant, the RS retains a positive introspection result computed before revocation, still within its original cache lifetime and applicable read deadline. | A refresh exchange, an authorization-code or device-code exchange, and re-delivery of a minted token all fail for G. A direct package fan-out sub-call also fails for G. A lifecycle write authenticated by a token revived solely by the restore fails. Introspection returns no active result for G. A read MAY succeed only under the cached-introspection exception in [Lifecycle durability](#lifecycle-durability), within the result's original cache lifetime and applicable read deadline. The restore MUST NOT restart either limit. In a variant, a positive introspection response computed before revocation reaches the RS more than 60 seconds after the RS sent the request. It authorizes neither a read nor a signed blob URL. In a variant, the restore runs through a declared path, and the backup predates redemption of an authorization code and consumption of a `single_use` grant: the code is not redeemed again, and the grant opens no second read window. | +| D2. Lifecycle authentication | A public client holds only an expired access token for a revoked grant. Another client presents a token for its own grant. | The expired token authenticates a query and cannot authenticate a write. Queries for another client's grant, an unknown grant, and an uncovered grant use the same HTTP handling, entry schema, and `invalid_grant` error. Only the requested `grant_id` differs; no field distinguishes those categories. | +| D3. Recovery after lifecycle compromise | The AS disables a public client's tokens for lifecycle use. The owner approves lifecycle recovery for the client's grants. | Disabled tokens get `invalid_token`. The recovery token authenticates queries and writes for the approved grants only, introspects `active: false`, and is rejected by the RS. Its token response is not a positive assessment. A request that mixes a recovery detail with a data-access detail is rejected with `invalid_authorization_details`. | +| D4. History loss | The AS loses its terminal-event history store. Each restore runs through a path that the AS declares it detects, unless a variant says otherwise. In a variant, the store ends before the latest position the AS recorded. While the history is unavailable, the owner revokes grant G with `delete`. In a second variant, for an AS that keeps loss-detection evidence outside the store's failure domain, event-specific evidence for erasure E is durable before E is acknowledged. The history then loses only the suffix containing E, while the independent evidence for E and the history epoch survive. Separately, the test injects failure while advancing the evidence. In a third variant, an AS with one store acknowledges erasure E, then restores a snapshot that predates E. In a fourth variant, the history is rolled back through a path that the AS does not declare, such as a revert of a virtual-machine snapshot. | Except in the fourth variant, the AS treats the history as not current under its declared mechanism. Its durability statement matches the failure domains the test exercises. It issues no token, active introspection result, processing authority, or positive assessment for any grant whose history it cannot establish; lifecycle queries get HTTP 503 `temporarily_unavailable` with `Retry-After`. It accepts the owner's revocation, shows it as pending, and applies it before any answer for G once the history is re-established. It MAY return G's erasure instruction meanwhile. In the second variant, every enabled enforcement point detects the suffix gap and fails closed. Failure to advance the evidence prevents acknowledgement of E. In the third variant, the AS detects the possible rollback and fails closed: it returns no positive assessment and no live credential for E's grant. In the fourth variant, the AS's durability statement names that path as undetected and states what it can revive. This outcome passes only because the AS does not declare the path as detected; the test requires no outside witness. | +| D5. Reports after revocation | The owner revokes a public client's grant at the AS with `delete`. The client holds only revoked tokens for the grant. | A revoked token authenticates the query that delivers the instruction. A `received` or `completed` report with that token gets `current_authentication_required`. The owner sees the stage sent, receipt not reported, and no deletion date. After the owner approves lifecycle recovery, the recovery token authenticates the client's report of its recorded receipt time and completion; the AS then shows the deletion date from that receipt. In a variant, the owner chooses `delete` in the client and the client conveys it with current client authentication and `reported_at`: the AS records that time as the client's receipt. Without `reported_at`, it records no receipt. | + +### Independent-recipient disclosure conformance cases {#independent-recipient-cases} + +A report MUST identify which assertions are protocol-visible and which are adapter-observed. Client disclosure assertions require an adapter that identifies the tested outbound, presentation, and storage surfaces. A report without those observations MUST mark those assertions UNVERIFIED. + +| Case | Fixture and required outcome | Observation | +|---|---|---| +| O1 | An active ordinary grant has an analytics purpose. The client attempts to send records to an independent recipient. The client prevents the disclosure. | Adapter-observed outbound payload and sink state. | +| O2 | Repeat O1 with a summary, score, embedding, shared-link response, and tool-call argument derived from the records. The client prevents each disclosure. | Adapter-observed, per supported surface; unsupported surfaces documented as not applicable. | +| O3 | Repeat O1 after grant expiry with `keep`, after `single_use` read-window closure, with an active token, and with a fresh positive assessment. None of these states authorizes disclosure. | Protocol-visible fixtures; adapter-observed release decision. | +| O4 | The purpose description says that data will be sent to a named adviser; a client claim promises deletion; the owner gives an action instruction to send. Without a covering registered permission, the client prevents independent disclosure. | Adapter-observed owner instruction and egress. | +| O5 | A party acts only for the client under the required flow-down. The client's classification does not treat that arrangement alone as independent disclosure. The client applies the same erasure deadlines to the party. Add an independent-reuse right to the fixture; the client then prevents disclosure without covering authority. | Adapter-observed arrangement, scope, relay, and outbound result. | +| O6 | An owner-held RS issues a fresh grant to client B. B reads using its own token. The rule does not reject the read merely because another client previously read the data. The RS never accepts client A's transferred token as B's grant. | Protocol-visible issuer, recipient, and read context, with adapter identity evidence where needed. | +| O7 | An authorization detail asks for an unknown release-permission URI. The AS returns `invalid_authorization_details` and issues no replacement ordinary grant. Discovery does not advertise the unsupported value. | Protocol-visible. | +| O8 | The client returns data to the owner within its applicable use terms. This rule does not block that return. Existing erasure, retention, and processing limits still apply. | Adapter-observed recipient identity and use eligibility. | +| O9 | The client cites the erasure exception for non-identifiable data. That exception alone does not authorize independent release. | Adapter-observed result lineage and release gate. | +| O9a | The client cites the learned-parameter exception. Not applicable until a supported registered profile can supply valid processing authority; a test reports it as not applicable, never as passed. Once applicable, that exception alone does not authorize independent release. | Adapter-observed result lineage and release gate. | +| O10 | A fixture supplies a binding legal disclosure obligation for a defined subset. The client releases no larger subset and retains the required record, unless the fixture prohibits that record. A merely legally permitted disclosure does not meet the exception. | Adapter-observed legal-basis fixture, payload, and record; legal validity itself is outside the test. | + +No test in this table proves the absence of undiscovered egress channels. A conformance report identifies its adapter coverage. ### Conformance test suite @@ -1696,7 +2390,7 @@ PDPP defines two token kinds at the resource server boundary: owner tokens and c For separated AS/RS deployments, the RS MUST authenticate to the AS introspection endpoint (RFC 7662) and enforce only from its response. It MUST NOT make a second AS lookup while handling the request. For co-located deployments, a local equivalent (shared database lookup or function call) is acceptable. Self-contained JWTs are allowed as an optimization but MUST NOT be the sole revocation mechanism. -Positive introspection results MUST NOT be cached longer than `min(token_exp, 60 seconds)`. This bounds the propagation window for revocation. +Positive introspection results MUST NOT be cached longer than `min(token_exp, 60 seconds)`. The cache lifetime runs from the time the RS sent the introspection request, or, for a co-located local equivalent, from the start of that validation. The RS MUST NOT use a result after that lifetime ends, cached or not. A delayed response does not extend it. This bounds read-access revocation propagation. An access token issued with or from a refresh-token family MUST be linked to that family and MUST have a short, token-specific expiration no later than the family or grant expiration. A token response MUST derive `expires_in` from the access token's persisted expiration. It MUST omit `expires_in` when the access token has no expiration, which Section 7 does not permit for a `single_use` grant. An RFC 7662 response MUST likewise omit `exp` when no expiration exists. @@ -1733,23 +2427,27 @@ A client that gives records to an automated agent SHOULD treat them as untrusted | Role | Responsibilities | |------|----------------| -| **Authorization Server** | Validates purpose-code syntax and local policy; authenticates user; preserves semantic distinctions on the consent surface; validates stream/field/view/resource-id shape at grant issuance; resolves views to field lists; issues access tokens; maintains grant lifecycle. | +| **Authorization Server** | Validates purpose-code syntax and local policy; authenticates user; preserves semantic distinctions on the consent surface; validates stream/field/view/resource-id shape at grant issuance; resolves views to field lists; issues access tokens; maintains grant lifecycle. Records dispositions and erasure instructions durably, and answers lifecycle queries. | | **Resource Server** | Validates token via introspection; for client requests, enforces stream, instance, fields, frozen time constraints, and resources against the resolved grant; for owner requests, enforces subject/source/connection/operation scope without requiring a grant; never reinterprets authorization from a current declaration. | -| **Client** | Submits well-formed selection requests; uses access tokens; terminates on revocation; honors retention commitments. | +| **Client** | Submits well-formed selection requests; uses access tokens; terminates on revocation; honors retention commitments; performs no operation that a processing permission covers without that permission and its defining profile's authority. Meets its held-data duties: reconciliation, erasure, and relay to parties acting for it. | ### Revocation {#revocation} -The owner MAY revoke a grant at the AS by a deployment-defined means. A binding MAY also let a client revoke a credential it holds. When a client revokes a refresh token, the AS MUST end every grant that the token's family covers, and every access token issued under those grants. Revoking a superseded refresh token of the family has the same effect. When a client revokes an access token, the AS MUST end that token. The AS MUST also end the token's grants, but only when no refresh-token family covers them. Where client revocation is supported, disconnect therefore requires revoking the refresh-token family. Revoking an access token disconnects only when no refresh-token family covers its grants. Ending one grant among several that share a credential is a grant-level action at the AS. It MUST NOT revoke the shared credential or end the other grants. +The owner MAY revoke a grant at the AS by a deployment-defined means. Every owner revocation carries a disposition for held data ([Ending paths](#ending-paths)). The AS MAY also end a grant for a security reason, with the effects that [Ending paths](#ending-paths) defines. A binding MAY also let a client revoke a credential it holds. When a client revokes a refresh token, the AS MUST end every grant that the token's family covers, and every access token issued under those grants. Revoking a superseded refresh token of the family has the same effect. When a client revokes an access token, the AS MUST end that token. The AS MUST also end the token's grants, but only when no refresh-token family covers them. Where client revocation is supported, disconnect therefore requires revoking the refresh-token family. Revoking an access token disconnects only when no refresh-token family covers its grants. Ending one grant among several that share a credential is a grant-level action at the AS. It MUST NOT revoke the shared credential or end the other grants. In the OAuth binding, client-initiated revocation is [RFC 7009](https://www.rfc-editor.org/rfc/rfc7009) token revocation. Support is OPTIONAL. An AS that offers clients a way to disconnect SHOULD support it. An AS that supports it MUST advertise `revocation_endpoint` in its [RFC 8414](https://www.rfc-editor.org/rfc/rfc8414) metadata. RFC 7009 Section 2.1 leaves the effect on related tokens and on the grant to AS policy; the rules above fix that policy. -There is no push revocation channel in v0.1. Revocation propagation is bounded by the introspection cache TTL (maximum 60 seconds), whoever starts the revocation. The AS MUST reflect revocation immediately in introspection: the revoked grant is inactive at once. A token that covers another active grant stays active; a token with no active grant is `active: false`. No later than 60 seconds after revocation, a request that uses the revoked grant fails. When the token is bound to no other active grant, the request fails with HTTP 401 and Bearer error `invalid_token`. The structured error code is `grant_revoked` when authenticated context establishes the cause, otherwise `authentication_error` (see Section 8, Errors). A binding in which one credential covers several grants defines the failure while the credential stays active. +The revocation request MAY carry `pdpp_disposition`, with the value `keep` or `delete`, to convey the owner's choice for every grant the revoked refresh-token family or package covers, including grants already ended or consumed ([Disconnect in the client](#client-disconnect)). Recording the disposition MUST NOT change the `read_state` or `ended_at` of a grant that had already expired or been revoked, and MUST NOT change the clocks of any existing instruction. An AS that supports RFC 7009 revocation MUST accept the parameter and MUST reject any other value with `invalid_request`. The AS records the disposition only when the request carries current client authentication ([Grant lifecycle operation](#grant-lifecycle)). Without it, the AS still ends the grants but records no disposition. A recorded `delete` creates an erasure instruction for each grant in that scope. With `delete`, the request MAY carry `reported_at`, reporting the owner's choice time in the client. Its validation and receipt-recording rules are those of `pdpp_disposition=delete` in the grant lifecycle operation. Absence of that time MUST NOT make the AS record request arrival as first receipt. + +Before it applies any effect of a revocation request that carries a recorded disposition, the AS MUST durably retain the request's complete grant scope, including grants already ended or consumed, the disposition, any `reported_at`, and credential binding. The AS MUST record a conveyed disposition before, or atomically with, the refresh-family revocation that carries it. A matching retry MAY finish that recorded operation after its own effects have revoked the credential. It MUST NOT authorize a new scope, disposition, or report with that credential. The AS returns HTTP 200 only when every requested ending and disposition is durable; otherwise it returns HTTP 503 with `Retry-After`. Retries preserve existing instruction identifiers and clocks. -On a 401 response with Bearer error `invalid_token`, the client MUST stop using that access token. On a `grant_revoked` error, the client MUST stop further requests against that grant. A client MUST NOT treat an inactive token as proof of revocation: the token may instead have expired or lost its refresh-token family. The HTTP status governs over an unknown error code, as Section 8 states. Companion profiles define how their active work is terminated. +There is no push revocation channel in v0.1. Read-access revocation propagation is bounded by the introspection cache TTL (maximum 60 seconds), whoever starts the revocation. The AS MUST reflect revocation immediately in introspection: the revoked grant is inactive at once. A token that covers another active grant stays active; a token with no active grant is `active: false`. No later than 60 seconds after revocation, a request that uses the revoked grant fails. When the token is bound to no other active grant, the request fails with HTTP 401 and Bearer error `invalid_token`. The structured error code is `grant_revoked` when authenticated context establishes the cause, otherwise `authentication_error` (see Section 8, Errors). A binding in which one credential covers several grants defines the failure while the credential stays active. A client learns whether it may keep and use held data only from token responses, the [grant lifecycle operation](#grant-lifecycle), or the owner's choice in the client ([Disconnect in the client](#client-disconnect)); a failed read only prompts a query. -Revocation stops future access only. Data already delivered to the client before revocation is governed by the grant's `retention` policy and applicable legal obligations. +On a 401 response with Bearer error `invalid_token`, the client MUST stop using that access token. On a `grant_revoked` error, the client MUST stop further requests against that grant. A client MUST NOT treat an inactive token as proof of revocation: the token may instead have expired or lost its refresh-token family. The HTTP status governs over an unknown error code, as Section 8 states. Before further use of held data of that grant, the client MUST start a grant lifecycle query, which is an attempt and not a successful answer ([Positive assessment and reconciliation](#reconciliation)). Companion profiles define how their active work is terminated. -Revocation is not deletion. v0.1 does not define an active erasure signal or downstream deletion callback. +Revocation ends future reads. Under a grant that carries a processing permission, it also ends processing authority over data already delivered, within the defining profile's cessation bound (Section 7). Revocation alone does not request erasure: held data then follows the grant's surviving-use terms and the client's held-data duties ([Held data after a grant ends](#held-data)). When the owner chooses `delete`, the erasure instruction requires the client to stop using and to delete its copy, its derivatives, and the copies of every party acting for it ([Erasure](#erasure)). + +Erasure reaches the client by pull, through the grant lifecycle operation, or by the owner's choice in the client. AS silence starts no additional held-data use or deletion deadline (Section 12). v0.1 defines no push channel for erasure and no proof of deletion. --- @@ -1765,7 +2463,7 @@ The `purpose_code` URI enables purpose declaration, consent display, registratio ### Auditability and transparency boundary -PDPP core defines the authorization, grant, and disclosure semantics that make auditing and transparency possible. This includes stable identifiers and state transitions such as `grant_id`, `client_id`, `subject_id`, `purpose_code`, stream and resource identifiers, timestamps, and grant lifecycle states. +PDPP core defines the authorization, grant, and disclosure semantics that make auditing and transparency possible. This includes stable identifiers and state transitions such as `grant_id`, `client_id`, `subject_id`, `purpose_code`, `processing_permissions`, stream and resource identifiers, timestamps, and grant lifecycle states. PDPP core does not define a local audit-log schema, storage model, retention period for operational logs, or a user-facing disclosure-history interface. Implementations MAY maintain local records of grant issuance, disclosure, sync, token use, and revocation under local policy. @@ -1773,7 +2471,7 @@ If interoperable audit or transparency events are standardized in the future, th ### Retention -The `retention` field is a structured policy declaration and policy commitment by the data recipient. PDPP does not technically enforce retention. Enforcement is through legal agreements or contractual obligations, with a trust registry supporting admission and accountability rather than enforcement. This is an intentional design choice, consistent with how OAuth 2.0 treats scope compliance. +The `retention` field is a structured policy declaration and policy commitment by the data recipient. PDPP does not technically enforce retention. Enforcement is through legal agreements or contractual obligations, with a trust registry supporting admission and accountability rather than enforcement. This is an intentional design choice, consistent with how OAuth 2.0 treats scope compliance. The held-data and erasure duties of Section 7 are client conformance duties of the same kind: the lifecycle operation makes them executable, and a conforming client's records make a breach attributable. --- @@ -1789,7 +2487,8 @@ The `retention` field is a structured policy declaration and policy commitment b - Resource server query API with cursor-based pagination and grant enforcement - Incremental sync for every stream via `changes_since` - Tombstones for records that leave a client's view -- Owner-authenticated user erasure (`DELETE /v1/streams/{stream}/records/{id}`) +- Owner-authenticated deletion of a record at the RS (`DELETE /v1/streams/{stream}/records/{id}`) +- Client duties for held data after a grant ends, owner-requested erasure of client-held copies, and the grant lifecycle operation (Section 7) - Self-export via owner token (SHOULD-level Core RS conformance, see Section 9 item 13) - Conformance definitions for all roles @@ -1797,9 +2496,9 @@ The `retention` field is a structured policy declaration and policy commitment b | Concern | Status | |---------|--------| -| Authorization server interface | Introspection endpoint contract defined here; full AS interface informational only in v0.1 | +| Authorization server interface | The authorization request, token result, AS metadata members, introspection, revocation, grant lifecycle operation, and lifecycle recovery are defined here. Consent-screen layout, owner authentication, and other AS endpoints are not | | Ingest and sync-state endpoints | Defined by the Collection Profile; not required for Core RS | -| Conformance test suite | Planned but not defined in v0.1 | +| Conformance test suite | Planned but not defined in v0.1. Section 9 lists the held-data cases such a suite exercises | | Webhook / push ingestion | Deferred | | Source lifecycle actions | Deferred (e.g., deleting source data after export) | | Event-driven collection triggers | Deferred; architecturally distinct from the pull-based Collection Profile | @@ -1811,17 +2510,27 @@ The `retention` field is a structured policy declaration and policy commitment b | Point-in-time reconstruction | Deferred (reconstructing full state at a past timestamp) | | Canonical view naming vocabulary | Deferred; will be informed by implementation experience | | Predicate-based grant scoping | Deferred; see [Predicate-based grant scoping](#predicate-based-grant-scoping) | -| Derivative data | Deferred and unresolved; v0.1 authorizes reads of declared streams and states no default for the output of compute over them | +| Derivative data | New derived sources and durable derived datasets remain deferred. Derivatives are [PDPP data](#data-concepts): held-data, retention, and erasure duties reach them (Section 7), and AI training on them is governed by [AI training](#ai-training). Independent-recipient disclosure follows the rule in Section 7. The optional [extended access profile](spec-access-extension) defines bounded presentation of authorized input, not new source or grant authority. | +| Independent-recipient disclosure | Requires a registered processing permission expressly covering the disclosure (Section 7). This version defines none. A future permission must define the complete recipient and disclosure contract under Section 6; ordinary purpose-compatible use supplies no such authority. | | Cross-source category grants | Deferred; grants bind to a single `source.id` in v0.1 | -| Active erasure signal | Deferred; revocation stops future access and is not a deletion request. No erasure signal to the recipient is defined | +| Push delivery and proof of deletion | Not specified in this version. Erasure reaches the client by pull, through the grant lifecycle operation (Section 7). Core defines no issuer-initiated notification to a client and no proof of deletion; the client keeps an accountability record | +| Use of held data while the AS is unreachable | Core specifies that the client keeps held data, may use it as the grant permits, and retries (Section 7). Core sets no use or deletion deadline that runs because the AS is silent. Known erasure, retention, and processing deadlines still bind | +| Record-level erasure and correction | Not specified in this version. The owner can delete a record at the RS (Section 8), but Core defines no request to erase or correct an individual record in copies a client holds. An erasure instruction covers all held data of one grant, and its scope is implicit in `grant_id`. Narrowing uses erasure and a new grant (Section 7). A sync tombstone means only that a record left the client's authorized view; it is not an instruction to forget the record. A grant never acquires duties that its approved contract does not define, and an AS rejects unsupported mandatory semantics (Section 6, Unknown members) | +| Clinical records and continued use after deletion | Not specified in this version: how a change of authority interacts with duties that govern clinical records, including correction, retention, and continued use. The legal-retention exception covers only legally required retention, and gives no general right to continued clinical or other use after the owner chooses `delete` (Section 7) | +| Issuer succession and estate | Not specified in this version: how existing grants are handled when an issuer stops operating or an owner dies, including who may act for the owner. A new issuer cannot answer for grants of an old one. Before an AS stops answering, it offers dispositions and warns about undelivered deletes (Section 7) | | Session refresh | Deferred; no signal asks the owner to renew source-side authentication. A `continuous` grant can stay valid while collection pauses | -| Request-side freshness requirements | Deferred; freshness is response-side only (`captured_at`, `status`, `last_attempted_at`) | +| Request-side freshness requirements | Deferred; freshness is response-side only, as a per-instance `last_success_at` (Section 8) | +| Collection coverage and degradation signals | Deferred to a future extension. Core reports no completeness (coverage) or degradation signal, and no signal that supports a claim that data does not exist at the source (Section 8) | | Minimum-data defaults | Decided for v0.1: a stream request names `fields`, a `view`, or the explicit `fields: ["*"]` marker (Section 6); `necessity` defaults to `optional`; an omitted `time_range` means no temporal constraint; `"name": "*"` requests all declared streams | | Subgrants | Deferred; access under a grant is not transferable. A second party needs its own grant | -| Client grant management | Deferred; a client can revoke a credential (Section 10), but Core defines no client operation that ends one grant while other grants share its credential | -| Change of client ownership and undisclosed sub-processing | Deferred; no change-of-control record, revocation trigger, or recipient sub-processing disclosure mechanism. `client_claims` is not an ownership record | +| Client grant management | Deferred; a client can revoke a credential (Section 10), query grant lifecycle, and report on erasure (Section 7). Its only operation that ends one grant while other grants share its credential conveys an owner's erasure request (Section 7) | +| Change of client ownership and undisclosed sub-processing | Deferred; no change-of-control record, revocation trigger, or recipient sub-processing disclosure mechanism. `client_claims` is not an ownership record. Moving held data to a different party under a change of control is [independent-recipient disclosure](#independent-recipient-disclosure) unless that party acts for the client | | Client bulk export | Deferred; owner self-export is SHOULD (Section 9). A client pages through the query under its grant | | Owner-operated authorization server (UMA-style) | Not introduced; see Section 3. | +| Cross-source reference resolution | Deferred; Core does not resolve the target instance of a `resource_ref` to another source, and a resource server serves such a reference in the redacted form (Section 4) | +| Instance-qualified resources | Deferred; in v0.1 a stream with `resources` covers exactly one instance, and the AS rejects `resources` with more than one instance (Section 6) | +| Globally resolvable subject identifiers | Out of scope, except as a `subject.id` that the owner explicitly chooses to disclose to a client (Section 7). Core defines no format, resolution, or proof of control for such an identifier | +| Proof of subject control | Deferred; v0.1 defines no proof that a grant is bound to a key the subject controls. Candidate companion profiles include pairwise DIDs with proof of control and unlinkable proofs such as BBS signatures (draft-irtf-cfrg-bbs-signatures) or AnonCreds link secrets | | Real-time streaming | Different spec needed | ### Predicate-based grant scoping {#predicate-based-grant-scoping} @@ -1836,7 +2545,7 @@ The recommended future direction for this capability is declaration-defined para ### Extensions -PDPP capabilities beyond this specification (for example, search or aggregation interfaces) are defined in companion profiles, not by extending Core semantics. Implementations MUST NOT change the meaning of Core-granted access via extensions: a grant issued under this specification authorizes exactly what Sections 7 and 8 define, regardless of what additional capabilities a deployment offers. Optional capabilities MUST be discoverable via declared metadata rather than assumed to be present. Unrecognized declared capabilities MUST be ignorable by clients. A full capability-advertisement grammar is deliberately deferred to a future version. +PDPP capabilities beyond this specification (for example, search or aggregation interfaces) are defined in companion profiles, not by extending Core semantics. Implementations MUST NOT change the meaning of Core-granted access via extensions: a grant issued under this specification authorizes exactly what Sections 6, 7, and 8 define, including any processing permission it carries, regardless of what additional capabilities a deployment offers. `processing_permissions` is a Core field; an extension cannot add or widen a processing permission. Optional capabilities MUST be discoverable via declared metadata rather than assumed to be present. Unrecognized declared capabilities MUST be ignorable by clients. A full capability-advertisement grammar is deliberately deferred to a future version. ### Specification governance @@ -1861,12 +2570,39 @@ interface BlobRef { fetch_url?: string; // Injected by resource server at read time; absent in producer output } -interface ResourceRef { +interface ResourceRef { // As a producer emits it source_id: string; // SourceDeclaration source.id absolute URI stream: string; record_id: string | string[]; } +// As a resource server serves it: resolved only when the target passes every grant constraint for its stream, else redacted +type ServedResourceRef = + | (ResourceRef & { instance_id: string }) + | { source_id: string; stream: string; redacted: true }; // No record_id or instance_id + +// Served by the query API; within a stream, (instance_id, id) identifies a record +interface ResponseRecord { + object: 'record'; + id: string; // Canonical key string + instance_id: string; // Opaque instance handle; identity is (instance_id, id) + stream: string; + data: Record<string, unknown>; + emitted_at: string; +} + +// --- Freshness (response metadata) --- + +// One entry for each instance the query context authorizes for the stream +interface FreshnessEntry { + instance_id: string; // Opaque instance handle, as on records + last_success_at: string | null; // RFC 3339; truncated to pdpp_freshness_granularity_seconds for client tokens; null = no reportable timestamp +} + +type OwnerFreshnessEntry = FreshnessEntry & { + last_failure_at?: string | null; // Owner tokens only; never in a client-token response +}; + // --- Selection (request-time) --- type TimeRange = // At least one bound; RFC 3339 full-date or date-time matching the field's format @@ -1881,6 +2617,10 @@ type FieldSelection = type StreamRequest = FieldSelection & { name: string; necessity?: 'required' | 'optional'; // Default 'optional' + minimum?: { + fields?: string[]; + time_range?: { since: string; until: string }; + }; instance_ids?: string[]; time_range?: TimeRange; resources?: string[]; // Canonical key strings per compound key encoding @@ -1908,8 +2648,9 @@ type SelectionRequest = { purpose_code: string; purpose_description?: string; access_mode: 'single_use' | 'continuous'; + processing_permissions?: string[]; // Unique absolute URIs; closed set (Section 6); absent or empty = none retention?: { - max_duration: string; + max_duration: string; // ISO 8601 duration in days, PnD on_expiry: 'delete' | 'anonymize'; }; client_claims?: { commitments?: string[] }; @@ -1927,7 +2668,7 @@ type TimeConstraint = TimeRange & { interface StreamGrant { name: string; - instance_ids: string[]; // Non-empty, unique, and stream-scoped + instance_ids: string[]; // Non-empty and unique; pairwise per client; a handle names one instance across the source's streams fields: string[]; // Non-empty and authoritative for RS enforcement time_constraint?: TimeConstraint; resources?: string[]; // Canonical key strings per compound key encoding @@ -1937,24 +2678,59 @@ interface DataGrant { version: '0.1.0'; grant_id: string; issued_at: string; - subject: { id: string }; + subject: { id: string }; // Pairwise identifier for this client client: { client_id: string; client_display?: Record<string, unknown> }; source: SourceObject; source_declaration: { version: string }; purpose_code: string; // URI purpose_description?: string; access_mode: 'single_use' | 'continuous'; + processing_permissions?: string[]; // Exact approved set; present only when non-empty; confers no read access streams: StreamGrant[]; selection_preset?: string; retention?: { - max_duration: string; // ISO 8601 duration - on_expiry: 'delete' | 'anonymize'; + max_duration: string; // ISO 8601 duration in days, PnD, counted from the first acquisition of each record + on_expiry: 'delete' | 'anonymize'; // Applied at each record's retention ceiling; an erasure instruction always requires deletion }; - expires_at?: string; // ISO 8601; absent means no expiry - grantors?: Array<{ id: string; capacity: string }>; // present only for representative approval + expires_at?: string; // ISO 8601; required when processing_permissions includes AI training; otherwise absent means no expiry + grantors?: Array<{ id: string; capacity: string }>; // present only for representative approval; id is pairwise per client extensions?: Record<string, unknown>; // keyed by absolute profile URI } +// --- Grant lifecycle operation (Section 7) --- + +type Disposition = 'keep' | 'delete'; // pdpp_disposition on revocation; only 'delete' is a lifecycle write + +interface ErasureInstruction { + instruction_id: string; + accepted_at: string; // RFC 3339; when the AS durably accepted the instruction + effective_at: string; // accepted_at, or the end of the grant for an advance election + stop_use_by: string; // effective_at plus the stop-use bound +} + +interface GrantLifecycleAnswer { + grant_id: string; + assessed_at: string; // RFC 3339; when the AS computed the answer + read_state: 'active' | 'window_closed' | 'expired' | 'revoked'; + ended_at?: string; // Present only when read_state is 'expired' or 'revoked' + held_data: 'permitted' | 'erase'; // 'permitted' is a positive assessment + erasure?: ErasureInstruction; // Present only when held_data is 'erase' +} + +interface GrantLifecycleError { + grant_id: string; + error: 'invalid_grant' | 'current_authentication_required' | 'invalid_instruction'; +} + +interface GrantLifecycleResponse { + grants: Array<GrantLifecycleAnswer | GrantLifecycleError>; // One entry per requested grant_id, in request order +} + +interface GrantLifecycleRecoveryDetail { + type: 'https://pdpp.dev/grant-lifecycle'; + grant_ids: [string, ...string[]]; +} + // --- Source Declaration --- interface StreamView { @@ -2034,11 +2810,19 @@ interface SourceDeclaration { interface PDPPIntrospectionResponse { active: boolean; pdpp_token_kind?: string; // Core defines 'owner' and 'client'; companion profiles may add kinds (unknown kinds are unauthorized for Core operations) - subject_id?: string; + subject_id?: string; // Enforcement identifier; may be internal; never disclosed to a client grant_id?: string; // Present for client tokens client_id?: string; // Present for client tokens exp?: number; // Unix timestamp - authorization_details?: Array<Record<string, unknown>>; // Approved RFC 9396 detail with Section 7 enforcement constraints + authorization_details?: Array<{ type: string; grant: DataGrant }>; // One element per authorized grant (Section 7 authorization result) + pdpp_instance_bindings?: InstanceBinding[]; // RS-only; never returned to a client +} + +interface InstanceBinding { + source_id: string; + stream?: string; // Present for client tokens; absent for owner tokens + instance_id: string; // The grant's handle, or the owner's handle + rs_instance: string; // Opaque; the RS resolves it to a stored instance } // --- Tombstones (response objects) --- @@ -2046,6 +2830,7 @@ interface PDPPIntrospectionResponse { interface ClientTombstone { object: 'record'; id: string; // Canonical key string + instance_id: string; // Opaque instance handle stream: string; deleted: true; // No data, deleted_at, or emitted_at @@ -2070,15 +2855,16 @@ Purpose codes are URIs. The following codes are defined by PDPP. Implementers ma | `https://pdpp.dev/purpose/analytics` | Analyzing user data to produce insights for the user. | | `https://pdpp.dev/purpose/export` | Exporting data for the user's own use. | | `https://pdpp.dev/purpose/agent_context` | Providing context to a personal AI agent. | -| `https://pdpp.dev/purpose/ai_training` | Using data to train AI models. The AS MUST follow the consent rule in [AI training consent](#ai-training-consent) before issuing any grant with this purpose code. This is a protocol-level requirement, not merely advisory. | | `https://pdpp.dev/purpose/research` | Academic or market research. | +A purpose code states what a use serves and never confers a processing permission. AI training is the processing permission `https://pdpp.dev/processing/ai_training` (Section 6), not a purpose. Earlier drafts defined the purpose code `https://pdpp.dev/purpose/ai_training`. It is withdrawn, is not reassigned, and confers no training authority. + --- ## Appendix B: Relationship to the Data Transfer Project (DTI) PDPP and DTI are complementary protocols addressing different concerns. PDPP defines parameterized consent and disclosure semantics (the grant is the consent artifact; the query API is the disclosure mechanism). DTI defines canonical data models and transfer adapters (the mechanics of moving data between systems). -The two protocols can chain: a PDPP grant can authorize access to data that a DTI transfer then moves, using PDPP stream schemas to carry DTI canonical data model payloads. Formal integration between PDPP grants and DTI transfer manifests is a separate effort; no integration document is currently specified. +The two protocols can chain: a PDPP grant can authorize access to data that a DTI transfer then moves, using PDPP stream schemas to carry DTI canonical data model payloads. Formal integration between PDPP grants and DTI transfer manifests is a separate effort; no integration document is currently specified. A client that moves held PDPP data to a party that does not act for it makes an [independent-recipient disclosure](#independent-recipient-disclosure), which v0.1 does not authorize. Note: "Data Transfer Project" is referred to as DTI (Data Transfer Initiative) in current usage, reflecting its evolution from the original DTP initiative. diff --git a/spec-data-query-api.md b/spec-data-query-api.md index de5de5b70..cf8b7d101 100644 --- a/spec-data-query-api.md +++ b/spec-data-query-api.md @@ -1,7 +1,7 @@ # PDPP Data Query API v0.1.0 Status: Superseded -Date: 2026-08-29 (last corrected); superseded 2026-04-12 +Date: 2026-10-06 (last corrected); superseded 2026-04-12 > **Note:** This document was written before Core Section 8 was expanded to normatively define the RS query interface. [Core Section 8 (Resource Server Interface)](spec-core.md#resource-server-interface) is authoritative for current query syntax, including the canonical `filter[{field}]` / `filter[{field}][op]` shapes, declaration-driven `query.range_filters` and `query.expand`, and the `limit_clamped` warning behavior. This file is retained for historical reference and should not be used for implementation. Where it disagrees with Core Section 8, Core Section 8 prevails — in particular, the `limit`, `expand_limit`, search, and error-table sections below predate the current contract and are stale. @@ -60,23 +60,17 @@ Returns the streams available under the current grant. "object": "stream", "name": "conversations", "record_count": 2196, - "last_updated": "2026-03-28T15:01:00Z", - "freshness": { - "captured_at": "2026-03-28T15:01:00Z", - "status": "current", - "last_attempted_at": "2026-03-28T15:01:00Z" - } + "freshness": [ + { "instance_id": "inst_Hc7vM3sD", "last_success_at": "2026-03-28T15:00:00Z" } + ] }, { "object": "stream", "name": "messages", "record_count": 48302, - "last_updated": "2026-03-28T15:01:00Z", - "freshness": { - "captured_at": "2026-03-28T15:01:00Z", - "status": "current", - "last_attempted_at": "2026-03-28T15:01:00Z" - } + "freshness": [ + { "instance_id": "inst_Hc7vM3sD", "last_success_at": "2026-03-28T15:00:00Z" } + ] } ] } @@ -96,12 +90,9 @@ Returns full source stream metadata, including schema, primary key, cursor field "object": "stream_metadata", "name": "conversations", "record_count": 2196, - "last_updated": "2026-03-28T15:01:00Z", - "freshness": { - "captured_at": "2026-03-28T15:01:00Z", - "status": "current", - "last_attempted_at": "2026-03-28T15:01:00Z" - }, + "freshness": [ + { "instance_id": "inst_Hc7vM3sD", "last_success_at": "2026-03-28T15:00:00Z" } + ], "schema": { "type": "object", "properties": { @@ -120,15 +111,15 @@ Returns full source stream metadata, including schema, primary key, cursor field ### Freshness metadata -The resource server MAY include a `freshness` object on stream listings, stream metadata, and record-list responses. +The resource server MAY include a `freshness` array on stream listings, stream metadata, and record-list responses. [Core Section 8 (Freshness metadata)](spec-core.md#freshness) is authoritative. -Freshness is server-observed response metadata, not a grant term. It reports what the server knows about the recency of the underlying data relevant to the response. It does not widen or narrow access rights, and it does not guarantee that the source has not changed since `captured_at`. +Freshness is server-observed response metadata, not a grant term. The array has one entry for each instance that the grant, or the owner scope, authorizes for the stream, whatever the page contains. It does not widen or narrow access rights, and it does not guarantee that the source has not changed since `last_success_at`. | Field | Type | Description | |-------|------|-------------| -| `captured_at` | ISO 8601 or null | Time of the most recent successful collection or source confirmation that could have affected the response. null if unknown. | -| `status` | enum | `current`, `stale`, or `unknown`. | -| `last_attempted_at` | ISO 8601 or null | Time of the most recent attempted refresh relevant to the response, if tracked. | +| `instance_id` | string | The instance handle (Core Section 4, Response records). | +| `last_success_at` | RFC 3339 date-time or null | Completion time of the most recent successful collection or source confirmation that could affect records visible under the full authorized scope of the query. Coarsened in client-token responses. null means only that no timestamp is reportable. | +| `last_failure_at` | RFC 3339 date-time or null | Owner token only. Never present in a client-token response. | ### List records @@ -170,11 +161,9 @@ PDPP-Version: 2026-03-28 "url": "/v1/streams/conversations/records", "has_more": true, "next_cursor": "eyJjcmVhdGVkX2F0IjoiMjAyNi0wMy0yNVQxODoyMjoxMVoiLCJpZCI6ImNvbnZfMDFKUVc4TTJSNyJ9", - "freshness": { - "captured_at": "2026-03-28T15:01:00Z", - "status": "current", - "last_attempted_at": "2026-03-28T15:01:00Z" - }, + "freshness": [ + { "instance_id": "inst_Hc7vM3sD", "last_success_at": "2026-03-28T15:00:00Z" } + ], "data": [ { "object": "record", diff --git a/spec-mcp-profile.md b/spec-mcp-profile.md new file mode 100644 index 000000000..53e96d1fb --- /dev/null +++ b/spec-mcp-profile.md @@ -0,0 +1,68 @@ +# PDPP Model Context Protocol (MCP) read profile + +Status: Draft extension profile; profile version 0.1.0 +Date: 2026-10-13 + +## 1. Scope + +This profile binds an MCP Streamable HTTP resource to PDPP-granted data access. It defines the additional obligations for a PDPP-governed MCP surface, not a replacement for Core's resource-server interface. + +The key words MUST, MUST NOT, REQUIRED, SHALL, SHALL NOT, SHOULD, SHOULD NOT, RECOMMENDED, MAY, and OPTIONAL have the meanings defined in RFC 2119 and RFC 8174 when capitalized. + +A conformance claim MUST identify the profile version, MCP resource identifier, covered sources, and covered tools or operations. It MUST identify any supported features of the [extended access profile](spec-access-extension). The claim MUST NOT imply coverage of unlisted data or operations. + +A claim names its role. A server claim covers the MCP server and the authorization and resource servers it relies on. It MUST state that it makes no claim about client or host behavior. A client or host claim covers the MCP client and the host that runs it. It requires every applicable Core client duty, including the held-data duties in Section 3, across tool results, transcripts, derivatives, memory stores, and processors. A storage behavior that a conformance test cannot observe is reported UNVERIFIED. Compatibility with MCP authorization and tool calls alone does not establish client or host conformance. + +## 2. Authorization binding + +The MCP client, authorization server, and resource server MUST satisfy the [MCP HTTP authorization requirements](https://modelcontextprotocol.io/specification/2026-07-28/basic/authorization), including protected-resource metadata, resource indicators, audience validation, and the prohibition on token passthrough. + +The MCP server MUST resolve each data-access token to an active Core client grant or an extended-access grant package. It MUST reject owner tokens and tokens intended for the owner control plane. Package acceptance MUST follow the extended access profile; it does not permit package tokens at Core endpoints. + +A downstream request MUST use a credential intended for the downstream resource and preserve the applicable grant restrictions. An upstream credential with broader permissions MUST NOT widen the MCP client's approved access. When the MCP server and the PDPP resource server are separate protected resources, the same AS MUST issue the downstream credential for the same grant, or for the same package and children. The deployment defines how the MCP server obtains it, for example by OAuth 2.0 Token Exchange ([RFC 8693](https://www.rfc-editor.org/rfc/rfc8693)). + +Downstream credential issuance remains subject to Core's access-mode and refresh-family rules. OAuth token exchange does not exempt an issuance from those rules. Before approval, a separated-resource deployment MUST reject a requested `single_use` flow that would require a later access-token issuance not permitted by those rules; it MUST NOT silently substitute continuous access, issue a replacement grant, or reopen the read window. A conformance claim MUST state this limitation. + +Clients and authorization servers MUST follow Core's authorization-result requirements. The client MUST inspect the complete resolved result before its first data-disclosing tool call. Optional owner selection and package issuance MUST follow the extended access profile, rather than MCP-specific grant formats. + +In this profile, a client's pairwise value for a subject, grantor, or instance is the identifier that Core's [Pairwise identifiers](spec-core#pairwise-identifiers) rules give that client. It includes a `subject.id` that the owner chose to disclose to that client. + +## 3. Tool disclosure + +The MCP server MUST map each data-disclosing operation to its applicable Core grant or package child grants and enforce their resolved restrictions on every call. It MUST reject ambiguous mappings. Tool annotations and tool availability MUST NOT substitute for authorization. + +With a package token, the child is always explicit. Every data-disclosing tool call, except the child-discovery tool below, MUST carry a `grant_id` argument, and each such tool MUST declare `grant_id` in its input schema. A call names exactly one child unless the tool accepts a list of `grant_id` values to fan out. Such a tool MUST make one sub-call per named child. It MUST NOT combine the constraints of several children or compute a result across children. It returns an envelope with one entry per named child, labeled with its `grant_id`. Each entry is either that child's result or that child's error object, including `package_child_inactive` with the text below. The tool result has `isError: true` only when every entry is an error. No tool selects a child implicitly or reads all children by default. The server MUST reject a missing, malformed, or unknown `grant_id` before it processes the call, with a tool result that has `isError: true`. Clients do not reliably validate arguments against the input schema, so this check belongs to the server. + +The MCP server MUST offer a callable child-discovery tool, scoped to the presented package token. For each child the tool returns the `grant_id`, source, purpose, any `processing_permissions`, streams with their `instance_ids`, access mode, and current read status. The read status describes read access only. It is not a lifecycle answer or a [positive assessment](spec-core#reconciliation). Tool text, annotations, and server instructions never confer a processing permission; only a grant's `processing_permissions` carries one, under Core ([Processing permissions](spec-core#processing-permissions)). Any subject, grantor, or instance identifier it returns is the client's pairwise value from the child grant ([Pairwise identifiers](spec-core#pairwise-identifiers)), and it lists only the handles that the child grant lists. It MUST NOT return records, derived facts, or grants, sources, or instances that the token does not cover. The discovery tool takes no `grant_id` argument; it is the child-discovery exemption of the extended access profile. Server instructions MAY also describe the children, but they are fixed at initialization and cannot show later revocation, so they do not replace the tool. + +When the server forwards a package-authorized call to a PDPP resource server, it MUST target a package endpoint in that resource server's declared package surface, never a Core-only endpoint. Each downstream request MUST name the same child and, when the call names an instance, the same `instance_id`. Over HTTP it uses the `PDPP-Grant-Id` header defined by the extended access profile. + +When a call names one child, that child is inactive, and the package token is active, the server MUST return a tool result with `isError: true`. In a fan-out call, the same error object and text go in that child's entry, and the envelope rule above sets `isError`. For a call to a tool that selects one child, `structuredContent.error` MUST contain `code` equal to `package_child_inactive` and `grant_id` naming the child. For a fan-out call, that error object MUST appear in the corresponding `structuredContent.results` entry, as defined below. Its text content MUST state that access under that grant has ended, that the call must not be retried, and that the owner can be asked if the access is needed again. For example: "Access to grant grt_8f72a1b3 has ended. Do not retry this call. Ask the owner if this access is needed again." The server MUST NOT answer this case with a transport-level HTTP 401 or 403. A client MUST NOT start re-authorization automatically on `package_child_inactive`, and the server MUST NOT substitute another child. When no child is active, the package token is inactive and the server returns HTTP 401 with Bearer error `invalid_token`. + +Tool results identify records as Core does. Every record or tombstone in a tool result carries `instance_id` next to `id`, and that pair identifies the record within its stream. The handle is the one the applicable grant lists: the Core grant, or the named child's grant. A `resource_ref` is resolved or redacted and a `blob_ref` `fetch_url` carries `instance_id`, as Core Section 4 defines. A tool that reads one record takes an `instance_id` argument, which is REQUIRED when the applicable grant lists more than one handle for the stream. A tool that fetches a blob always takes an `instance_id` argument. Before it looks up the record or blob, the server MUST reject a call that lacks a required `instance_id` with a tool result that has `isError: true`. It MUST treat a handle that the applicable grant does not list as not found. + +Core lets a resource server omit `freshness`, and this profile does not require it. A successful non-fan-out tool result that returns a Core response or a presentation result MUST put that object in `structuredContent.data`. The tool result MUST preserve every Core `freshness` array unchanged at its Core location within that object. For stream metadata and record lists, the path is `structuredContent.data.freshness`; for stream listings, it is `structuredContent.data.data[i].freshness` on each stream item. A presentation result carries any top-level `freshness` at `structuredContent.data.freshness` and MUST carry its `inputs` at `structuredContent.data.inputs`. These metadata members MUST NOT also appear at the top level of `structuredContent`. + +A call to a fan-out tool with a one-element `grant_id` list is still a fan-out call. For a fan-out call, `structuredContent.results` MUST contain one entry per named child. Each successful entry carries `grant_id` and its response or presentation result in `data`, preserving the same `freshness` and `inputs` locations within that object. Each failed entry carries `grant_id` and `error`. The envelope MUST NOT carry combined `freshness` or `inputs`. + +The tool's output schema MUST declare these member locations whenever its results can carry them. Times are RFC 3339. MCP `annotations.lastModified` is not a substitute, because it states when a resource changed, not when collection last succeeded. + +A tool input schema, result, error, or server instruction MUST NOT contain an identifier for a subject, grantor, or instance that is not the client's pairwise value, such as the introspection `subject_id` or an `rs_instance`. + +Direct record and blob results MUST preserve Core disclosure, snapshot, expiry, and revocation semantics. Searches, counts, previews, and summaries MUST satisfy the extended access profile's bounded-presentation rules. Error results MUST respect the same disclosure boundary. + +Data that a client obtains in tool results is PDPP data held under the applicable grant or child. A host that keeps tool results, for example in conversation history or a memory store, holds that data. Core's held-data, reconciliation, and erasure duties apply to it ([Held data after a grant ends](spec-core#held-data)). A client or host claim under this profile requires them. This profile defines no lifecycle tool: the client uses the Core [grant lifecycle operation](spec-core#grant-lifecycle) at the authorization server. Tool text and annotations are never a lifecycle answer. + +Actions and their responses MUST follow Core's [existing-permissions and action-result rules](spec-core#existing-permissions), including its limited action-receipt allowance. This profile adds no action-permission vocabulary. + +## 4. Implementation guidance (informative) + +An MCP endpoint can use one ordinary grant; owner selection and grant packages are optional. Using those features requires client support for their authorization requests and complete grant results. Ordinary OAuth redirect support alone does not establish that compatibility. + +Some MCP SDKs discard unfamiliar token-response fields by default. Implementers should verify that their client preserves and inspects PDPP's complete authorization result, including on refresh. SDK customization or a grant-aware client may be necessary. + +Surveyed MCP clients hold one token per configured server and overwrite it on refresh. A package therefore fits their token storage: the client keeps one token and passes `grant_id` as an ordinary tool argument. The same clients pass a tool result with `isError: true` to the model without retrying or re-authorizing, while several treat HTTP 403 with `insufficient_scope` as a trigger for step-up authorization. For that reason an inactive child is a tool result and not a 403 challenge. Some clients show `isError` results to the model as plain content, so the text of the result has to explain itself. The survey shows compatibility of token storage and tool errors only. It does not show a complete conforming journey: request construction and inspection of the complete result still need PDPP-aware client support. Loss of the last child makes the token inactive, and the resulting 401 can start the host's authorization handling. + +For work that continues after re-authorization, a client can retain the source identifier and its pairwise `instance_id` handles as discovery hints within the same issuer, subject, and client context. Core keeps those handles stable for that client across grants. The client discovers the current children and inspects the complete authorization result before choosing a new `grant_id`; a source or instance handle does not select a child or confer authority. Several children can cover the same source or instance under different purposes or constraints. The server does not substitute a new child for an ended grant. + +Tool names and schemas remain deployment choices. This profile supplies a grant-enforcement claim, not a shared tool vocabulary or a guarantee of complete platform-data coverage. Applicable Core conformance remains required. diff --git a/spec-reference-implementation-examples.md b/spec-reference-implementation-examples.md index 1780a9f6f..1482c8c86 100644 --- a/spec-reference-implementation-examples.md +++ b/spec-reference-implementation-examples.md @@ -1,7 +1,7 @@ # PDPP Reference Implementation Examples Status: Illustrative -Date: 2026-09-29 +Date: 2026-10-13 These examples are illustrative sequences built from the current draft. They are not the normative source for wire shapes or role responsibilities. When an example and the live draft differ, the normative documents win: @@ -12,7 +12,7 @@ These examples are illustrative sequences built from the current draft. They are Two explicit limits apply in this file: -1. The authorization server HTTP interface is not normatively specified in v0.1, so authorization and token-exchange steps are shown as decoded request/response shapes rather than mandatory AS endpoints. +1. The owner-facing authorization interaction is deployment-specific, so authorization and token-exchange steps are shown as decoded request/response shapes rather than complete OAuth HTTP exchanges. Core specifies the client-visible token result, AS-to-RS introspection, and the grant lifecycle HTTP operation. 2. The Collection Profile standardizes the `START` envelope and its portable `scope`, but not every runtime-internal planning detail or execution hint a particular runtime may use around that envelope. --- @@ -70,7 +70,7 @@ This is the logical content carried in the OAuth authorization request. `client_ ### Step 2: Consent rendering -The authorization server preserves the semantic distinctions required by the draft. +The authorization server preserves the semantic distinctions required by the draft. This excerpt shows only those distinctions. Final owner review also shows the grant expiry, the selected account, the envelope identifiers that every record discloses, and what happens to held data after the grant ends, as Core Sections 4 and 6 require. > **Requester** > Concerts App @@ -146,15 +146,14 @@ PDPP-Version: 2026-04-06 "object": "list", "url": "/v1/streams/top_artists/records", "has_more": false, - "freshness": { - "captured_at": "2026-04-11T14:58:00Z", - "status": "current", - "last_attempted_at": "2026-04-11T14:58:00Z" - }, + "freshness": [ + { "instance_id": "inst_Rb3kT9wE", "last_success_at": "2026-04-11T14:00:00Z" } + ], "data": [ { "object": "record", "id": "4Z8W4fKeB5", + "instance_id": "inst_Rb3kT9wE", "stream": "top_artists", "data": { "id": "4Z8W4fKeB5", @@ -169,7 +168,7 @@ PDPP-Version: 2026-04-06 } ``` -`freshness` is response metadata. It tells the client what the server knows about recency. It is not itself a grant term. +`freshness` is response metadata. It has one entry for each instance that the grant lists for the stream, and it tells the client when the server last succeeded in collecting data relevant to the grant. It is not itself a grant term. ### Step 5: Later attempt to mint another client token @@ -363,15 +362,14 @@ PDPP-Version: 2026-04-06 "url": "/v1/streams/conversations/records", "has_more": false, "next_changes_since": "cs_T2wPd7Kx5NqB0mRz9LyVc4HgJ1sFa8Eu", - "freshness": { - "captured_at": "2026-04-11T15:12:01Z", - "status": "current", - "last_attempted_at": "2026-04-11T15:12:01Z" - }, + "freshness": [ + { "instance_id": "inst_Jm6pX2cV", "last_success_at": "2026-04-11T14:00:00Z" } + ], "data": [ { "object": "record", "id": "conv_003", + "instance_id": "inst_Jm6pX2cV", "stream": "conversations", "data": { "id": "conv_003", @@ -390,9 +388,9 @@ If this session had multiple pages, the follow-on `next_cursor` pages would stay --- -## Example 3: Retention and revocation are not deletion +## Example 3: Retention, revocation, and erasure -A sleep analysis app receives a one-time grant with a retention declaration. +A sleep analysis app receives a one-time grant with a retention declaration. The retained `sleep_sessions` schema requires `day`. ### Step 1: Issued grant @@ -404,23 +402,27 @@ A sleep analysis app receives a one-time grant with a retention declaration. "subject": { "id": "user_abc" }, "client": { "client_id": "sleep_app" }, "source": { "kind": "connector", "id": "https://registry.pdpp.dev/connectors/oura" }, - "manifest_version": "1.0.0", + "source_declaration": { "version": "2026-04-01" }, "purpose_code": "https://pdpp.dev/purpose/analytics", "purpose_description": "Analyze your sleep patterns", "access_mode": "single_use", "streams": [ { "name": "sleep_sessions", - "time_range": { - "since": "2026-03-12T00:00:00Z", - "until": "2026-04-11T00:00:00Z" + "instance_ids": ["inst_R7mT2qVx"], + "time_constraint": { + "field": "day", + "type": "date", + "since": "2026-03-12", + "until": "2026-04-11" }, "fields": [ "day", "total_sleep_duration", "sleep_score", "deep_sleep_duration" - ] + ], + "required_fields": ["day"] } ], "retention": { @@ -434,20 +436,22 @@ A sleep analysis app receives a one-time grant with a retention declaration. ### Step 2: User later revokes the grant -The AS marks the grant inactive. Further client access stops after revocation propagates through introspection. +The AS asks the user to choose `keep` or `delete` for the data the app already holds, with neither option preselected. It then marks the grant revoked and records the choice. Further client access stops after revocation propagates through introspection. ### Step 3: Further disclosure attempts fail ```http GET /v1/streams/sleep_sessions/records Authorization: Bearer pdpp_client_tok_sleep_001 -PDPP-Version: 2026-04-06 +PDPP-Version: 0.1 ``` +The token is inactive, and authenticated RS context establishes that its grant was revoked. The response is HTTP 401 with `WWW-Authenticate: Bearer error="invalid_token"`. If the cause were not established, the structured code would be `authentication_error`. + ```json { "error": { - "type": "permission_error", + "type": "authentication_error", "code": "grant_revoked", "message": "Grant has been revoked.", "request_id": "req_01JREVOCATION" @@ -458,8 +462,10 @@ PDPP-Version: 2026-04-06 ### Step 4: What revocation does and does not mean - Future disclosure stops. -- Data already delivered to the client remains governed by the grant's retention commitment and any applicable legal obligations. -- Revocation is not deletion. -- v0.1 does not define an active erasure signal telling the client to delete previously disclosed data immediately. +- Revocation alone does not request deletion. The user's disposition decides what happens to data already delivered. +- With `keep`, the app may go on using that data for the approved purpose until each record's 90-day retention ceiling, counted from when the app first received the record. +- With `delete`, the AS records an erasure instruction. The app stops using the data and deletes it, with its derivatives and its processors' copies, within the limits of Core Section 7. +- The app stops using this access token and starts a Core grant lifecycle query before further use of the data. The failed read is not a lifecycle answer. While it holds the data, it also queries at least daily, and retries a failed query as Core Section 7 requires. +- If the app cannot reach the AS, it keeps the data and retries. It cannot learn of a `delete` made at the AS until the AS answers again. A `delete` chosen inside the app binds at once, and the retention ceiling still applies. -That separation is intentional: the protocol should not imply downstream deletion when it cannot actually make it happen. +Core makes deletion an executable client duty. The stop-use bound runs from the instruction's effective time, and an app that learns later stops at once. The deletion bound runs from the app's first receipt. Core defines no proof of deletion: a conforming app's records make a breach attributable, not impossible.