@opendatalabs/personal-server-ts-core 1.33.8 → 1.34.1

package/dist/pdpp/redirect.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Redirect URI validation (RFC 6749 §3.1.2, §10.6; RFC 8252 §7.3).
+ *
+ * The authorization code travels to the client in this redirect. If the AS
+ * honours whatever `redirect_uri` a caller supplies, the attack is direct: an
+ * attacker opens an authorization session pointing at their own host, the
+ * owner sees a consent screen that looks entirely legitimate (it is — the AS
+ * generated it), approves, and the code is delivered to the attacker.
+ *
+ * **PKCE does not mitigate this.** PKCE binds the code to whoever chose the
+ * challenge, and in this attack that is the attacker. They hold the matching
+ * verifier, so they redeem the stolen code and receive a grant-bound token
+ * over the owner's personal data. Code interception and code *misdelivery* are
+ * different problems; §10.6 is the one that covers misdelivery.
+ *
+ * Validation is by exact match against the client's registered redirect URIs.
+ * RFC 6749 §3.1.2.2 requires registration, and §3.1.2.3 allows fuzzier
+ * matching only for clients that registered a full URI — we do not take that
+ * latitude. Prefix or subdomain matching is where open-redirect bugs live: a
+ * registered `https://app.example.com/cb` "matching"
+ * `https://app.example.com.evil.test/cb` or `https://app.example.com/cb/../x`
+ * is the classic failure. Exact string equality after normalization has no
+ * such edge, and the cost is that a client registers each callback it uses.
+ */
+export type RedirectFailureCode = "unregistered_redirect_uri" | "insecure_redirect_uri" | "malformed_redirect_uri" | "no_registered_redirect_uris";
+export interface RedirectFailure {
+    code: RedirectFailureCode;
+    message: string;
+}
+/**
+ * Registered metadata for a client, as the deployment holds it.
+ *
+ * `redirect_uris` is required and non-empty for the code flow: a client with
+ * no registered callback cannot safely receive a code, and defaulting to
+ * "accept anything" would reintroduce exactly the hole this module closes.
+ */
+export interface RegisteredRedirectPolicy {
+    client_id: string;
+    redirect_uris: string[];
+}
+/**
+ * Validate a requested redirect URI against the client's registered set.
+ *
+ * Returns null when the URI is acceptable. Every rejection is deliberately
+ * the same shape, so a caller probing for registered URIs learns only that
+ * theirs was not one.
+ */
+export declare function validateRedirectUri(requested: string | undefined, policy: RegisteredRedirectPolicy | null): RedirectFailure | null;
+/**
+ * Whether a redirect failure may be reported *by redirecting*.
+ *
+ * RFC 6749 §4.1.2.1 is explicit: when the redirect URI is invalid or
+ * unregistered, the AS MUST NOT automatically redirect the user-agent to it.
+ * Doing so would turn the authorization endpoint into an open redirector and
+ * would hand the attacker the error response they were fishing for. Every
+ * failure from `validateRedirectUri` is therefore reported directly to the
+ * caller and never as a redirect.
+ */
+export declare const REDIRECT_FAILURES_ARE_NEVER_REDIRECTED: true;
+//# sourceMappingURL=redirect.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"redirect.d.ts","sourceRoot":"","sources":["../../src/pdpp/redirect.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAKH,MAAM,MAAM,mBAAmB,GAC3B,2BAA2B,GAC3B,uBAAuB,GACvB,wBAAwB,GACxB,6BAA6B,CAAC;AAElC,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,mBAAmB,CAAC;IAC1B,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,wBAAwB;IACvC,SAAS,EAAE,MAAM,CAAC;IAClB,aAAa,EAAE,MAAM,EAAE,CAAC;CACzB;AAmBD;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CACjC,SAAS,EAAE,MAAM,GAAG,SAAS,EAC7B,MAAM,EAAE,wBAAwB,GAAG,IAAI,GACtC,eAAe,GAAG,IAAI,CAqExB;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,sCAAsC,EAAG,IAAa,CAAC"}

package/dist/pdpp/redirect.js

@@ -0,0 +1,125 @@
+/**
+ * Redirect URI validation (RFC 6749 §3.1.2, §10.6; RFC 8252 §7.3).
+ *
+ * The authorization code travels to the client in this redirect. If the AS
+ * honours whatever `redirect_uri` a caller supplies, the attack is direct: an
+ * attacker opens an authorization session pointing at their own host, the
+ * owner sees a consent screen that looks entirely legitimate (it is — the AS
+ * generated it), approves, and the code is delivered to the attacker.
+ *
+ * **PKCE does not mitigate this.** PKCE binds the code to whoever chose the
+ * challenge, and in this attack that is the attacker. They hold the matching
+ * verifier, so they redeem the stolen code and receive a grant-bound token
+ * over the owner's personal data. Code interception and code *misdelivery* are
+ * different problems; §10.6 is the one that covers misdelivery.
+ *
+ * Validation is by exact match against the client's registered redirect URIs.
+ * RFC 6749 §3.1.2.2 requires registration, and §3.1.2.3 allows fuzzier
+ * matching only for clients that registered a full URI — we do not take that
+ * latitude. Prefix or subdomain matching is where open-redirect bugs live: a
+ * registered `https://app.example.com/cb` "matching"
+ * `https://app.example.com.evil.test/cb` or `https://app.example.com/cb/../x`
+ * is the classic failure. Exact string equality after normalization has no
+ * such edge, and the cost is that a client registers each callback it uses.
+ */
+/** Loopback hosts, where RFC 8252 §7.3 permits plain http for native apps. */
+const LOOPBACK_HOSTS = new Set(["127.0.0.1", "[::1]", "::1", "localhost"]);
+/**
+ * Normalize for comparison without loosening the match.
+ *
+ * `URL` resolves dot-segments and lowercases scheme and host, so
+ * `https://App.Example.com/cb/../cb` and `https://app.example.com/cb` compare
+ * equal — that is canonicalization, not fuzzy matching. Query and fragment are
+ * preserved, because a registered URI that carries a query is a different
+ * endpoint from one that does not.
+ */
+function normalize(raw) {
+    try {
+        return new URL(raw);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Validate a requested redirect URI against the client's registered set.
+ *
+ * Returns null when the URI is acceptable. Every rejection is deliberately
+ * the same shape, so a caller probing for registered URIs learns only that
+ * theirs was not one.
+ */
+export function validateRedirectUri(requested, policy) {
+    if (!requested || requested.length === 0) {
+        return {
+            code: "malformed_redirect_uri",
+            message: "redirect_uri is required",
+        };
+    }
+    const url = normalize(requested);
+    if (!url) {
+        return {
+            code: "malformed_redirect_uri",
+            message: "redirect_uri is not a valid absolute URI",
+        };
+    }
+    // RFC 6749 §3.1.2: the endpoint URI MUST NOT include a fragment. A fragment
+    // is also how a target gets smuggled past a naive prefix check.
+    if (url.hash.length > 0) {
+        return {
+            code: "malformed_redirect_uri",
+            message: "redirect_uri must not include a fragment component",
+        };
+    }
+    // Scheme gate before anything else. `javascript:` and `data:` are the
+    // XSS-on-redirect shapes; everything non-http(s) is refused outright rather
+    // than enumerated, so a scheme nobody thought of is refused by default.
+    const isLoopback = LOOPBACK_HOSTS.has(url.hostname);
+    if (url.protocol === "http:") {
+        // RFC 8252 §7.3: loopback http is the native-app redirect, and is fine.
+        if (!isLoopback) {
+            return {
+                code: "insecure_redirect_uri",
+                message: "redirect_uri must use https except for loopback addresses",
+            };
+        }
+    }
+    else if (url.protocol !== "https:") {
+        return {
+            code: "insecure_redirect_uri",
+            message: `redirect_uri scheme '${url.protocol}' is not permitted`,
+        };
+    }
+    if (!policy || policy.redirect_uris.length === 0) {
+        // No registration means no safe target. Failing closed here is the whole
+        // point: an AS that falls back to "trust the request" when it has no
+        // policy has no policy.
+        return {
+            code: "no_registered_redirect_uris",
+            message: "client has no registered redirect URIs; register one before requesting authorization",
+        };
+    }
+    // Exact match after canonicalization. No prefix, no subdomain, no wildcard.
+    const matched = policy.redirect_uris.some((candidate) => {
+        const registered = normalize(candidate);
+        return registered !== null && registered.toString() === url.toString();
+    });
+    if (!matched) {
+        return {
+            code: "unregistered_redirect_uri",
+            message: "redirect_uri does not exactly match a registered redirect URI",
+        };
+    }
+    return null;
+}
+/**
+ * Whether a redirect failure may be reported *by redirecting*.
+ *
+ * RFC 6749 §4.1.2.1 is explicit: when the redirect URI is invalid or
+ * unregistered, the AS MUST NOT automatically redirect the user-agent to it.
+ * Doing so would turn the authorization endpoint into an open redirector and
+ * would hand the attacker the error response they were fishing for. Every
+ * failure from `validateRedirectUri` is therefore reported directly to the
+ * caller and never as a redirect.
+ */
+export const REDIRECT_FAILURES_ARE_NEVER_REDIRECTED = true;
+//# sourceMappingURL=redirect.js.map

package/dist/pdpp/redirect.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"redirect.js","sourceRoot":"","sources":["../../src/pdpp/redirect.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,8EAA8E;AAC9E,MAAM,cAAc,GAAG,IAAI,GAAG,CAAC,CAAC,WAAW,EAAE,OAAO,EAAE,KAAK,EAAE,WAAW,CAAC,CAAC,CAAC;AAyB3E;;;;;;;;GAQG;AACH,SAAS,SAAS,CAAC,GAAW;IAC5B,IAAI,CAAC;QACH,OAAO,IAAI,GAAG,CAAC,GAAG,CAAC,CAAC;IACtB,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,mBAAmB,CACjC,SAA6B,EAC7B,MAAuC;IAEvC,IAAI,CAAC,SAAS,IAAI,SAAS,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACzC,OAAO;YACL,IAAI,EAAE,wBAAwB;YAC9B,OAAO,EAAE,0BAA0B;SACpC,CAAC;IACJ,CAAC;IAED,MAAM,GAAG,GAAG,SAAS,CAAC,SAAS,CAAC,CAAC;IACjC,IAAI,CAAC,GAAG,EAAE,CAAC;QACT,OAAO;YACL,IAAI,EAAE,wBAAwB;YAC9B,OAAO,EAAE,0CAA0C;SACpD,CAAC;IACJ,CAAC;IAED,4EAA4E;IAC5E,gEAAgE;IAChE,IAAI,GAAG,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACxB,OAAO;YACL,IAAI,EAAE,wBAAwB;YAC9B,OAAO,EAAE,oDAAoD;SAC9D,CAAC;IACJ,CAAC;IAED,sEAAsE;IACtE,4EAA4E;IAC5E,wEAAwE;IACxE,MAAM,UAAU,GAAG,cAAc,CAAC,GAAG,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;IACpD,IAAI,GAAG,CAAC,QAAQ,KAAK,OAAO,EAAE,CAAC;QAC7B,wEAAwE;QACxE,IAAI,CAAC,UAAU,EAAE,CAAC;YAChB,OAAO;gBACL,IAAI,EAAE,uBAAuB;gBAC7B,OAAO,EAAE,2DAA2D;aACrE,CAAC;QACJ,CAAC;IACH,CAAC;SAAM,IAAI,GAAG,CAAC,QAAQ,KAAK,QAAQ,EAAE,CAAC;QACrC,OAAO;YACL,IAAI,EAAE,uBAAuB;YAC7B,OAAO,EAAE,wBAAwB,GAAG,CAAC,QAAQ,oBAAoB;SAClE,CAAC;IACJ,CAAC;IAED,IAAI,CAAC,MAAM,IAAI,MAAM,CAAC,aAAa,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACjD,yEAAyE;QACzE,qEAAqE;QACrE,wBAAwB;QACxB,OAAO;YACL,IAAI,EAAE,6BAA6B;YACnC,OAAO,EACL,sFAAsF;SACzF,CAAC;IACJ,CAAC;IAED,4EAA4E;IAC5E,MAAM,OAAO,GAAG,MAAM,CAAC,aAAa,CAAC,IAAI,CAAC,CAAC,SAAS,EAAE,EAAE;QACtD,MAAM,UAAU,GAAG,SAAS,CAAC,SAAS,CAAC,CAAC;QACxC,OAAO,UAAU,KAAK,IAAI,IAAI,UAAU,CAAC,QAAQ,EAAE,KAAK,GAAG,CAAC,QAAQ,EAAE,CAAC;IACzE,CAAC,CAAC,CAAC;IAEH,IAAI,CAAC,OAAO,EAAE,CAAC;QACb,OAAO;YACL,IAAI,EAAE,2BAA2B;YACjC,OAAO,EAAE,+DAA+D;SACzE,CAAC;IACJ,CAAC;IAED,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,sCAAsC,GAAG,IAAa,CAAC"}

package/dist/pdpp/resolve.d.ts

@@ -0,0 +1,109 @@
+/**
+ * PDPP Core §6→§7 resolution: turn a validated selection request into the
+ * explicit grant facts that get frozen at issuance.
+ *
+ * Every request-only convenience dies here. Wildcards and presets expand to
+ * concrete stream rows, views resolve to field lists, omitted fields become
+ * the declaration's full field set, omitted instance handles resolve against
+ * the owner's connection inventory, and `time_range` freezes against the
+ * declaration's `consent_time_field`. §7 is explicit that none of these
+ * conveniences are continuing authority in the grant — the RS must never have
+ * to resolve anything, which is also what the AS→RS contract promises.
+ *
+ * Resolution runs against the same retained snapshot `selection.ts` validated
+ * against. Passing a newer declaration here is the bug §9 AS item 16 exists to
+ * prevent: it would let a later declaration widen an in-flight authorization.
+ */
+import { type DeclarationSnapshot, type RequestedStream, type SelectionRequest, type StreamGrant, type StreamRequest, type TimeRange } from "./types.js";
+/**
+ * The owner's v0.2 narrowing decisions, keyed by stream name.
+ *
+ * Every member narrows and none widens. That is enforced by intersection
+ * rather than by trust: a choice is applied against the request's own upper
+ * limit, so a caller that forwards a tampered choice gets the ceiling, not an
+ * escalation. Instance picks stay where they already are — overlaid onto the
+ * `InstanceInventory` — because they narrow *eligibility*, which is owner
+ * state rather than request shape.
+ *
+ * Ignored entirely for a v0.1 request: that revision defines no narrowing
+ * step, and a v0.1 client's grant must be the same one it has always had.
+ */
+export interface OwnerChoices {
+    /** Streams the owner removed. Only an `optional` stream may appear. */
+    declined_streams?: string[];
+    /** Per-stream field narrowing, intersected with the requested allowlist. */
+    fields?: Record<string, string[]>;
+    /** Per-stream window narrowing, clamped into the requested window. */
+    time_ranges?: Record<string, TimeRange>;
+}
+/**
+ * The owner's connected instances for a source, as the AS knows them at
+ * resolution time. §6 is strict that omitting `instance_ids` never means
+ * fan-in: the AS resolves exactly one eligible handle or requires an explicit
+ * owner choice.
+ */
+export interface InstanceInventory {
+    /** Eligible opaque handles for a given stream, in the owner's connection state. */
+    eligibleFor(streamName: string): string[];
+}
+export type ResolutionFailureCode = "unknown_stream" | "unknown_instance" | "instance_choice_required" | "no_eligible_instance" | "unknown_view" | "empty_field_set"
+/** v0.2: a required stream's explicit minimum cannot be satisfied. */
+ | "minimum_not_met"
+/** v0.2: the owner declined a stream the request marks `required`. */
+ | "required_stream_declined"
+/** v0.2: nothing survived the owner's choices. No empty grants. */
+ | "no_streams_approved";
+export interface ResolutionFailure {
+    code: ResolutionFailureCode;
+    message: string;
+    /** The stream that could not be resolved, when the failure is stream-scoped. */
+    stream?: string;
+    /** For `instance_choice_required`: the handles the owner must choose between. */
+    candidates?: string[];
+}
+export type ResolutionResult = {
+    ok: true;
+    streams: StreamGrant[];
+    /**
+     * v0.2: optional streams the owner removed, or whose minimum their
+     * narrowing could not meet. Present only when non-empty, and only for
+     * v0.2 — an omitted stream is not a grant and must never read as
+     * authorized, so it travels beside the approved streams rather than in
+     * them.
+     */
+    omittedStreams?: string[];
+    /**
+     * v0.2: the requested upper limits, so the grant can record what was
+     * asked for beside what was approved.
+     */
+    requestedStreams?: RequestedStream[];
+} | {
+    ok: false;
+    failure: ResolutionFailure;
+};
+/**
+ * Expand the request's stream selections into the concrete list to resolve.
+ *
+ * A wildcard entry fans out to every declared stream, carrying its own
+ * per-stream parameters with it — §6 says a wildcard's `instance_ids` apply to
+ * every expanded stream, and each handle is then verified per stream by
+ * `resolveInstances`. A preset expands from the snapshot instead.
+ *
+ * Exported because the consent surface must expand a request the same way
+ * resolution does. `approval.ts` collects the owner's pending instance
+ * choices over these expanded streams; when it derived its own list from
+ * `request.streams` alone, a `selection_preset` expanded to nothing there and
+ * to two eligible instances here, so the owner was never asked and the
+ * request died as unresolvable. One expansion, two readers.
+ */
+export declare function expandSelections(request: SelectionRequest, snapshot: DeclarationSnapshot): StreamRequest[];
+/**
+ * Resolve every enforcement axis for a validated selection request.
+ *
+ * Call this before showing the final approval surface: §7 requires the
+ * approval artifact to contain the exact resolved instance handles, stream
+ * names, fields, resources, and temporal bounds, which only exist once this
+ * has run.
+ */
+export declare function resolveSelection(request: SelectionRequest, snapshot: DeclarationSnapshot, inventory: InstanceInventory, choices?: OwnerChoices): ResolutionResult;
+//# sourceMappingURL=resolve.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"resolve.d.ts","sourceRoot":"","sources":["../../src/pdpp/resolve.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAEL,KAAK,mBAAmB,EAExB,KAAK,eAAe,EACpB,KAAK,gBAAgB,EACrB,KAAK,WAAW,EAChB,KAAK,aAAa,EAElB,KAAK,SAAS,EACf,MAAM,YAAY,CAAC;AAEpB;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,YAAY;IAC3B,uEAAuE;IACvE,gBAAgB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC5B,4EAA4E;IAC5E,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;IAClC,sEAAsE;IACtE,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;CACzC;AAED;;;;;GAKG;AACH,MAAM,WAAW,iBAAiB;IAChC,mFAAmF;IACnF,WAAW,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;CAC3C;AAED,MAAM,MAAM,qBAAqB,GAC7B,gBAAgB,GAChB,kBAAkB,GAClB,0BAA0B,GAC1B,sBAAsB,GACtB,cAAc,GACd,iBAAiB;AACnB,sEAAsE;GACpE,iBAAiB;AACnB,sEAAsE;GACpE,0BAA0B;AAC5B,mEAAmE;GACjE,qBAAqB,CAAC;AAE1B,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,qBAAqB,CAAC;IAC5B,OAAO,EAAE,MAAM,CAAC;IAChB,gFAAgF;IAChF,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,iFAAiF;IACjF,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;CACvB;AAED,MAAM,MAAM,gBAAgB,GACxB;IACE,EAAE,EAAE,IAAI,CAAC;IACT,OAAO,EAAE,WAAW,EAAE,CAAC;IACvB;;;;;;OAMG;IACH,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAC1B;;;OAGG;IACH,gBAAgB,CAAC,EAAE,eAAe,EAAE,CAAC;CACtC,GACD;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,OAAO,EAAE,iBAAiB,CAAA;CAAE,CAAC;AAkV9C;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,gBAAgB,CAC9B,OAAO,EAAE,gBAAgB,EACzB,QAAQ,EAAE,mBAAmB,GAC5B,aAAa,EAAE,CAyBjB;AAED;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAC9B,OAAO,EAAE,gBAAgB,EACzB,QAAQ,EAAE,mBAAmB,EAC7B,SAAS,EAAE,iBAAiB,EAC5B,OAAO,CAAC,EAAE,YAAY,GACrB,gBAAgB,CAuGlB"}