@opendatalabs/personal-server-ts-core 1.33.7 → 1.34.0

package/dist/pdpp/review.d.ts

@@ -0,0 +1,280 @@
+/**
+ * PDPP Core §6/§7 consent review model and immutable review digest.
+ *
+ * Two jobs here, and they are related:
+ *
+ * 1. Build the review model Account/Web renders. §6 forbids flattening the
+ *    consent surface: requester identity, declaration-authored data
+ *    descriptions, structured policy declarations, and attributed client
+ *    claims are four distinct categories, and a client claim must never be
+ *    rendered in the same register as a protocol-enforced term. The model
+ *    below keeps them in four separate fields so a renderer cannot
+ *    accidentally merge them.
+ *
+ * 2. Compute a digest over the decision fields. §7 requires the approval
+ *    mutation to bind to an immutable review revision or digest, and to reject
+ *    approval if eligibility or the reviewed revision changed in the meantime.
+ *    That is what stops a resolved-then-widened race: the owner approves a
+ *    digest, and issuance re-derives the digest from what it is about to issue.
+ *    If they differ, the approval is stale and dies.
+ *
+ * The digest covers exactly the decision fields §7 enumerates, plus the
+ * normalized client claims when they were rendered. It deliberately does NOT
+ * cover `issued_at` or `grant_id`, which do not exist yet at review time.
+ */
+import { type ResolvedCommitments } from "./commitments.js";
+import { type ClientClaims, type ClientDisplay, type DeclarationSnapshot, type OwnerConditions, type RecipientTerms, type RequestedStream, type Retention, type SelectionRequest, type StreamGrant } from "./types.js";
+/** How the AS resolved requester identity, and how much it actually knows. */
+export interface RequesterIdentity {
+    client_id: string;
+    /** Resolved per §6 precedence. Falls back to `client_id` when nothing else exists. */
+    display_name: string;
+    display?: ClientDisplay;
+    /**
+     * §6 obligation 5: verified domain control is named, never presented as an
+     * unqualified "verified app". Absent means no positive trust signal, and the
+     * surface must show an unverified indicator.
+     */
+    verified_domain?: string;
+    /** True only for a local registration or trust-registry admission decision. */
+    app_approved: boolean;
+}
+/** One stream row as the owner reviews it, with declaration-authored copy. */
+export interface ReviewStream {
+    name: string;
+    /** Declaration-authored description. Its own category — not a client claim. */
+    description?: string;
+    /**
+     * §5 stream `display.label` — the short consent-card name for this stream,
+     * e.g. "Who you follow" rather than `following_accounts`.
+     *
+     * Read from the retained declaration snapshot, never from the request. §5
+     * forbids the requesting client from authoring or supplementing it, and the
+     * AS is the only role that can hold that line, because the renderer cannot
+     * tell from one payload which member the client wrote.
+     */
+    display_label?: string;
+    /**
+     * §5 stream `display.detail` — what the data includes and, where relevant,
+     * what it EXCLUDES. Same provenance rule as `display_label`.
+     */
+    display_detail?: string;
+    instance_ids: string[];
+    fields: string[];
+    time_constraint?: {
+        field: string;
+        since?: string;
+        until?: string;
+    };
+    resources?: string[];
+    /**
+     * v0.2 consent-flow control. `optional` means the owner may remove this
+     * stream; the surface must not present it as compulsory.
+     */
+    necessity?: "required" | "optional";
+    /**
+     * v0.2: the fields and window the client asked for, before the owner's
+     * narrowing. The surface needs both ends to render a narrowing control at
+     * all — `fields` above is the current proposal, this is its ceiling.
+     */
+    requested_fields?: string[];
+    requested_time_range?: {
+        since?: string;
+        until?: string;
+    };
+    /**
+     * v0.2: the floor. A surface that lets the owner narrow below this is
+     * offering a choice that will refuse issuance, so it needs to know where
+     * the floor is in order to stop short of it — or to say why it cannot.
+     */
+    minimum?: {
+        fields?: string[];
+        time_range?: {
+            since: string;
+            until: string;
+        };
+    };
+}
+/**
+ * An already-active grant this same client holds for this owner, so the
+ * consent surface can say what is already shared. Deliberately excludes
+ * tokens, consent evidence, and the review digest — informational only, never
+ * an authority the RS or AS re-derives from.
+ */
+export interface ExistingGrant {
+    grant_id: string;
+    issued_at: string;
+    expires_at?: string;
+    access_mode: "single_use" | "continuous";
+    purpose_code: string;
+    streams: Array<{
+        name: string;
+        fields: string[];
+    }>;
+}
+/**
+ * The four semantic categories §6 requires a conformant consent surface to
+ * keep distinct. A renderer that wants to flatten them has to do so
+ * deliberately; it cannot do so by accident.
+ */
+export interface ConsentReviewModel {
+    /** Category 1: who is asking. */
+    requester: RequesterIdentity;
+    /** Category 2: declaration-authored data descriptions + protocol-enforced terms. */
+    data: {
+        /**
+         * `display_name` is §5's top-level `display.name` — the human name for the
+         * source. It accompanies `id` rather than replacing it: `id` is the
+         * protocol-enforced fact and the one 6.1-5 requires the owner to be able
+         * to see, so a surface that showed only the friendly name would hide which
+         * source was actually resolved.
+         */
+        source: {
+            kind: string;
+            id: string;
+            display_name?: string;
+        };
+        source_declaration_version: string;
+        access_mode: "single_use" | "continuous";
+        streams: ReviewStream[];
+        /**
+         * v0.2: optional streams the owner's current choices have removed, so the
+         * surface can keep showing them as declined rather than making them
+         * vanish. v0.2 forbids presenting optional selections as compulsory; a
+         * declined stream that disappears from the review is the mirror failure —
+         * the owner cannot see what they turned off, or turn it back on.
+         */
+        omitted_streams?: string[];
+        expires_at?: string;
+    };
+    /** Category 3: structured policy declarations. */
+    policy: {
+        purpose_code: string;
+        purpose_description?: string;
+        /**
+         * True when the code is absent from the PDPP registry. §9 AS item 6:
+         * this drives *rendering* (show the description or raw URI), never
+         * rejection.
+         */
+        purpose_unregistered: boolean;
+        retention?: Retention;
+        /**
+         * §6: the sole purpose code with a protocol-level consent requirement.
+         * The surface must collect explicit affirmative consent when this is set.
+         */
+        requires_explicit_ai_training_consent: boolean;
+    };
+    /** Category 4: attributed, unverifiable, non-enforceable client claims. */
+    client_claims?: {
+        /** Always rendered as "<name> says:" — never as a protocol term. */
+        attributed_to: string;
+        commitments: string[];
+    };
+    /** Digest over the decision fields. The approval must carry this back. */
+    review_digest: string;
+    /**
+     * This client's other active grants for this owner, newest first. Absent
+     * when there are none — kept out of the digest since it is informational,
+     * not a decision field, and can change between requests without staling
+     * the review.
+     */
+    existing_grants?: ExistingGrant[];
+}
+export declare function isRegisteredPurposeCode(code: string): boolean;
+/**
+ * Normalize client claims before binding. §6 requires the *normalized exact*
+ * claims to be bound into the approval artifact, so the digest has to be
+ * computed over a canonical form — otherwise re-rendering with different
+ * whitespace would spuriously invalidate an approval.
+ */
+export declare function normalizeClientClaims(claims: ClientClaims | undefined): string[] | undefined;
+/**
+ * The exact set of fields the digest covers. Kept as its own type so that
+ * adding a decision field to the grant without adding it here is a visible
+ * omission rather than a silent hole in the binding.
+ */
+interface ReviewDecisionFields {
+    subject_id: string;
+    client_id: string;
+    source_id: string;
+    source_kind: string;
+    source_declaration_version: string;
+    /** The digest of the retained snapshot, so a re-fetched declaration cannot pass. */
+    declaration_digest: string;
+    purpose_code: string;
+    purpose_description?: string;
+    access_mode: string;
+    streams: StreamGrant[];
+    /**
+     * v0.2: optional streams the owner's choices removed.
+     *
+     * This has to be a decision field, not just presentation. Two owners
+     * narrowing the same request to the same retained streams by different
+     * routes — one declining an optional stream, one narrowing it below its
+     * minimum — reach the same `streams` but reviewed different screens. More
+     * importantly, without it an approval could carry a narrowing the owner
+     * never saw whenever that narrowing only *removed* a stream, since removal
+     * leaves the surviving streams byte-identical.
+     */
+    omitted_streams?: string[];
+    retention?: Retention;
+    expires_at?: string;
+    /** Bound with attribution when rendered; stays outside the grant regardless. */
+    client_claims?: {
+        attributed_to: string;
+        commitments: string[];
+    };
+}
+export declare function computeReviewDigest(fields: ReviewDecisionFields): string;
+export interface BuildReviewInput {
+    subjectId: string;
+    request: SelectionRequest;
+    snapshot: DeclarationSnapshot;
+    /** The output of `resolveSelection` — fully concrete. */
+    resolvedStreams: StreamGrant[];
+    /** v0.2: `resolveSelection`'s `omittedStreams`, bound into the digest. */
+    omittedStreams?: string[];
+    /**
+     * v0.2: `resolveSelection`'s `requestedStreams`, the ceiling each retained
+     * stream was narrowed from. Rendering only — the resolved streams stay
+     * authoritative, and this stays out of the digest since it is a restatement
+     * of the request the session already pins, not a decision the owner makes.
+     */
+    requestedStreams?: RequestedStream[];
+    /**
+     * v0.2: conditions the owner attached beyond narrowing the data, and the
+     * standing terms that may cover them.
+     *
+     * Resolution happens here rather than in the caller so the review and the
+     * digest cannot disagree about which commitments were shown. A condition
+     * outside the recipient's authority makes the whole review unavailable —
+     * there is nothing valid to show the owner — so `buildConsentReview` throws
+     * the same `CommitmentsFailure` the issuance path reports. Callers that can
+     * present a failure to the owner call `resolveCommitments` first.
+     */
+    ownerConditions?: OwnerConditions;
+    standingTerms?: RecipientTerms;
+    /**
+     * Pre-resolved commitments, when the caller already ran
+     * `resolveCommitments` (issuance does, so it can report a refusal rather
+     * than throw). Takes precedence over the two members above.
+     */
+    commitments?: ResolvedCommitments;
+    requester: RequesterIdentity;
+    /** AS-policy grant expiry, when the deployment sets one. */
+    expiresAt?: string;
+    /** Declaration-authored stream descriptions, keyed by stream name. */
+    streamDescriptions?: Record<string, string>;
+    /** This client's other active grants for this owner, newest first. */
+    existingGrants?: ExistingGrant[];
+}
+/**
+ * Build the review model and its binding digest.
+ *
+ * The digest is computed from the same resolved streams that will be issued.
+ * `issueGrant` recomputes it and refuses to issue if it moved — see
+ * `issuance.ts`.
+ */
+export declare function buildConsentReview(input: BuildReviewInput): ConsentReviewModel;
+export {};
+//# sourceMappingURL=review.d.ts.map

package/dist/pdpp/review.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"review.d.ts","sourceRoot":"","sources":["../../src/pdpp/review.ts"],"names":[],"mappings":"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"}

package/dist/pdpp/review.js

@@ -0,0 +1,205 @@
+/**
+ * PDPP Core §6/§7 consent review model and immutable review digest.
+ *
+ * Two jobs here, and they are related:
+ *
+ * 1. Build the review model Account/Web renders. §6 forbids flattening the
+ *    consent surface: requester identity, declaration-authored data
+ *    descriptions, structured policy declarations, and attributed client
+ *    claims are four distinct categories, and a client claim must never be
+ *    rendered in the same register as a protocol-enforced term. The model
+ *    below keeps them in four separate fields so a renderer cannot
+ *    accidentally merge them.
+ *
+ * 2. Compute a digest over the decision fields. §7 requires the approval
+ *    mutation to bind to an immutable review revision or digest, and to reject
+ *    approval if eligibility or the reviewed revision changed in the meantime.
+ *    That is what stops a resolved-then-widened race: the owner approves a
+ *    digest, and issuance re-derives the digest from what it is about to issue.
+ *    If they differ, the approval is stale and dies.
+ *
+ * The digest covers exactly the decision fields §7 enumerates, plus the
+ * normalized client claims when they were rendered. It deliberately does NOT
+ * cover `issued_at` or `grant_id`, which do not exist yet at review time.
+ */
+import { createHash } from "node:crypto";
+import { resolveCommitments } from "./commitments.js";
+import { AI_TRAINING_PURPOSE, } from "./types.js";
+/**
+ * Purpose codes in the Appendix A initial registry. Membership drives display
+ * only. An unrecognized code is displayed from its description or raw URI and
+ * is never a rejection reason on its own (§9 AS item 6).
+ */
+const REGISTERED_PURPOSE_CODES = new Set([
+    "https://pdpp.dev/purpose/personalization",
+    "https://pdpp.dev/purpose/analytics",
+    "https://pdpp.dev/purpose/research",
+    "https://pdpp.dev/purpose/portability",
+    "https://pdpp.dev/purpose/ai_training",
+]);
+export function isRegisteredPurposeCode(code) {
+    return REGISTERED_PURPOSE_CODES.has(code);
+}
+/**
+ * Normalize client claims before binding. §6 requires the *normalized exact*
+ * claims to be bound into the approval artifact, so the digest has to be
+ * computed over a canonical form — otherwise re-rendering with different
+ * whitespace would spuriously invalidate an approval.
+ */
+export function normalizeClientClaims(claims) {
+    const commitments = claims?.commitments;
+    if (!commitments || commitments.length === 0)
+        return undefined;
+    const normalized = commitments
+        .map((c) => c.trim().replace(/\s+/g, " "))
+        .filter((c) => c.length > 0);
+    return normalized.length > 0 ? normalized : undefined;
+}
+/**
+ * Deterministic serialization. `JSON.stringify` preserves insertion order, so
+ * we sort keys explicitly — two structurally identical decisions must produce
+ * one digest regardless of how the objects were built.
+ */
+function canonicalize(value) {
+    if (value === null || typeof value !== "object") {
+        return JSON.stringify(value) ?? "null";
+    }
+    if (Array.isArray(value)) {
+        // Array order is meaningful (a field list's order is part of the decision
+        // the owner saw), so we do not sort array members.
+        return `[${value.map(canonicalize).join(",")}]`;
+    }
+    const entries = Object.entries(value)
+        .filter(([, v]) => v !== undefined)
+        .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
+    return `{${entries
+        .map(([k, v]) => `${JSON.stringify(k)}:${canonicalize(v)}`)
+        .join(",")}}`;
+}
+export function computeReviewDigest(fields) {
+    return createHash("sha256")
+        .update(canonicalize(fields), "utf8")
+        .digest("hex");
+}
+/**
+ * Build the review model and its binding digest.
+ *
+ * The digest is computed from the same resolved streams that will be issued.
+ * `issueGrant` recomputes it and refuses to issue if it moved — see
+ * `issuance.ts`.
+ */
+export function buildConsentReview(input) {
+    const { request, snapshot, resolvedStreams, requester } = input;
+    const normalizedClaims = normalizeClientClaims(request.client_claims);
+    const boundClaims = normalizedClaims
+        ? { attributed_to: requester.display_name, commitments: normalizedClaims }
+        : undefined;
+    // The commitments the owner will see, resolved from the request or the
+    // recipient's standing terms. These are decision fields: a commitment the
+    // owner never reviewed must not be issuable, so they go into the digest.
+    const commitments = input.commitments ?? resolveOrThrowCommitments(input);
+    const review_digest = computeReviewDigest({
+        subject_id: input.subjectId,
+        client_id: requester.client_id,
+        source_id: snapshot.source_id,
+        source_kind: snapshot.source_kind,
+        source_declaration_version: snapshot.version,
+        declaration_digest: snapshot.digest,
+        purpose_code: commitments.purpose_code,
+        purpose_description: commitments.purpose_description,
+        access_mode: request.access_mode,
+        streams: resolvedStreams,
+        ...(input.omittedStreams &&
+            input.omittedStreams.length > 0 && {
+            omitted_streams: input.omittedStreams,
+        }),
+        retention: commitments.retention,
+        expires_at: input.expiresAt,
+        client_claims: boundClaims,
+    });
+    return {
+        requester,
+        data: {
+            source: {
+                kind: snapshot.source_kind,
+                id: snapshot.source_id,
+                ...(snapshot.display?.name && {
+                    display_name: snapshot.display.name,
+                }),
+            },
+            source_declaration_version: snapshot.version,
+            access_mode: request.access_mode,
+            streams: resolvedStreams.map((s) => {
+                const asked = input.requestedStreams?.find((r) => r.name === s.name);
+                // §5 consent copy, read from the RETAINED SNAPSHOT. `request` is
+                // deliberately not consulted: that is the whole provenance guarantee.
+                const declared = snapshot.streams.find((d) => d.name === s.name);
+                return {
+                    name: s.name,
+                    // The deployment-supplied map still wins where a caller set it, so
+                    // this adds a source of copy without removing the existing one.
+                    ...((input.streamDescriptions?.[s.name] ?? declared?.description) && {
+                        description: input.streamDescriptions?.[s.name] ?? declared?.description,
+                    }),
+                    ...(declared?.display?.label && {
+                        display_label: declared.display.label,
+                    }),
+                    ...(declared?.display?.detail && {
+                        display_detail: declared.display.detail,
+                    }),
+                    instance_ids: s.instance_ids,
+                    fields: s.fields,
+                    ...(s.time_constraint && { time_constraint: s.time_constraint }),
+                    ...(s.resources && { resources: s.resources }),
+                    ...(asked && {
+                        necessity: asked.necessity,
+                        requested_fields: asked.fields,
+                        ...(asked.time_range && { requested_time_range: asked.time_range }),
+                        ...(asked.minimum && { minimum: asked.minimum }),
+                    }),
+                };
+            }),
+            ...(input.omittedStreams &&
+                input.omittedStreams.length > 0 && {
+                omitted_streams: input.omittedStreams,
+            }),
+            ...(input.expiresAt && { expires_at: input.expiresAt }),
+        },
+        policy: {
+            purpose_code: commitments.purpose_code,
+            ...(commitments.purpose_description && {
+                purpose_description: commitments.purpose_description,
+            }),
+            purpose_unregistered: !isRegisteredPurposeCode(commitments.purpose_code),
+            ...(commitments.retention && { retention: commitments.retention }),
+            requires_explicit_ai_training_consent: commitments.purpose_code === AI_TRAINING_PURPOSE,
+        },
+        ...(boundClaims && { client_claims: boundClaims }),
+        review_digest,
+        ...(input.existingGrants &&
+            input.existingGrants.length > 0 && {
+            existing_grants: input.existingGrants,
+        }),
+    };
+}
+/**
+ * Resolve commitments for a caller that cannot present a refusal.
+ *
+ * A condition outside the recipient's authority means there is no valid review
+ * to build — showing the owner the *unrefused* terms would be showing them a
+ * decision they cannot make. Throwing rather than silently falling back is
+ * what stops that: the issuance path resolves first and reports a refusal, and
+ * anything else fails loudly instead of rendering a lie.
+ */
+function resolveOrThrowCommitments(input) {
+    const resolved = resolveCommitments({
+        request: input.request,
+        ownerConditions: input.ownerConditions,
+        standingTerms: input.standingTerms,
+        declarationVersion: input.snapshot.version,
+    });
+    if (!resolved.ok)
+        throw new Error(resolved.failure.message);
+    return resolved.commitments;
+}
+//# sourceMappingURL=review.js.map

package/dist/pdpp/review.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"review.js","sourceRoot":"","sources":["../../src/pdpp/review.ts"],"names":[],"mappings":"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"}

package/dist/pdpp/selection.d.ts

@@ -0,0 +1,50 @@
+/**
+ * PDPP Core §6 selection-request validation.
+ *
+ * This is the shape gate that runs before consent. It answers one question:
+ * is this request expressible against the retained declaration snapshot? It
+ * does not resolve anything — `resolve.ts` does that, and only against the
+ * same snapshot this module validated against.
+ *
+ * "Fails neutrally" in §6 means the both/neither `streams`/`selection_preset`
+ * failure is a Source validation failure the binding maps to an error code; it
+ * must not leak which of the two the client got wrong, and it must not depend
+ * on any owner-specific state. We return a binding-neutral failure and let the
+ * OAuth/RAR layer map it to RFC 9396 `invalid_authorization_details`.
+ */
+import { type DeclarationSnapshot, type SelectionRequest } from "./types.js";
+/**
+ * Binding-neutral validation failure codes. The OAuth/RAR binding maps these
+ * to wire errors in `../../../server/src/routes/pdpp-authorize.ts`; Core
+ * itself stays binding-neutral (§9 AS item 5).
+ */
+export type SelectionFailureCode = 
+/** Both or neither of `streams` and `selection_preset`. */
+"source_validation_failed" | "unknown_stream" | "unknown_preset" | "unknown_view" | "unknown_field" | "unsupported_selection_parameter" | "invalid_resource_key"
+/**
+ * A v0.2 `minimum` the AS cannot interpret. Distinct from
+ * `unsupported_selection_parameter` (a v0.2 member on a v0.1 request) and
+ * from the issuance-time `access_denied` a well-formed but unsatisfiable
+ * minimum produces: only this one is fixable by the client resending.
+ */
+ | "invalid_minimum" | "invalid_request";
+export interface SelectionFailure {
+    code: SelectionFailureCode;
+    message: string;
+}
+export type SelectionValidation = {
+    ok: true;
+} | {
+    ok: false;
+    failure: SelectionFailure;
+};
+/**
+ * Validate one selection request against the retained declaration snapshot.
+ *
+ * The caller must have already retrieved and pinned `snapshot`; this function
+ * never fetches. §9 AS item 16 requires that the same snapshot carry through
+ * consent and issuance, so passing a freshly fetched declaration here and a
+ * different one to `resolveGrant` would defeat the whole guarantee.
+ */
+export declare function validateSelectionRequest(request: SelectionRequest, snapshot: DeclarationSnapshot): SelectionValidation;
+//# sourceMappingURL=selection.d.ts.map

package/dist/pdpp/selection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"selection.d.ts","sourceRoot":"","sources":["../../src/pdpp/selection.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAGL,KAAK,mBAAmB,EAExB,KAAK,gBAAgB,EAEtB,MAAM,YAAY,CAAC;AAEpB;;;;GAIG;AACH,MAAM,MAAM,oBAAoB;AAC9B,2DAA2D;AACzD,0BAA0B,GAC1B,gBAAgB,GAChB,gBAAgB,GAChB,cAAc,GACd,eAAe,GACf,iCAAiC,GACjC,sBAAsB;AACxB;;;;;GAKG;GACD,iBAAiB,GACjB,iBAAiB,CAAC;AAEtB,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,oBAAoB,CAAC;IAC3B,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,MAAM,mBAAmB,GAC7B;IAAE,EAAE,EAAE,IAAI,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,OAAO,EAAE,gBAAgB,CAAA;CAAE,CAAC;AAga1D;;;;;;;GAOG;AACH,wBAAgB,wBAAwB,CACtC,OAAO,EAAE,gBAAgB,EACzB,QAAQ,EAAE,mBAAmB,GAC5B,mBAAmB,CAwJrB"}