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

package/dist/pdpp/declaration.d.ts

@@ -0,0 +1,118 @@
+/**
+ * Bounded SourceDeclaration retrieval (§5 declaration acceptance, §10
+ * declaration retrieval hygiene).
+ *
+ * An AS that fetches a client-supplied URL is an SSRF engine unless it is
+ * fenced. The rules here are the fence: HTTPS only, no private or loopback or
+ * link-local address literals, a bounded redirect chain that is re-checked at
+ * every hop, a response size cap, and a timeout. Each redirect is validated
+ * again because a public hostname resolving to a public IP can redirect to
+ * `http://169.254.169.254/` and a one-shot check at the start would miss it.
+ *
+ * What this module deliberately does NOT do is decide whether a declaration is
+ * *trusted*. That is deployment policy (`DeclarationTrustPolicy`), applied
+ * explicitly by the caller, because "we fetched it safely" and "we accept its
+ * authority over this source" are different questions.
+ */
+import type { DeclarationSnapshot } from "./types.js";
+export declare const MAX_DECLARATION_BYTES: number;
+export declare const MAX_REDIRECTS = 3;
+export declare const DECLARATION_FETCH_TIMEOUT_MS = 5000;
+export type DeclarationFailureCode = "insecure_scheme" | "private_address" | "too_many_redirects" | "too_large" | "fetch_failed" | "invalid_document" | "digest_mismatch" | "source_id_mismatch" | "untrusted_source" | "declaration_equivocation" | "unsupported_version";
+export interface DeclarationFailure {
+    code: DeclarationFailureCode;
+    message: string;
+}
+export type DeclarationResult = {
+    ok: true;
+    snapshot: DeclarationSnapshot;
+} | {
+    ok: false;
+    failure: DeclarationFailure;
+};
+/**
+ * Explicit deployment trust policy. §1 of the delivery scope requires the AS to
+ * apply an *explicit* policy rather than trusting whatever it can reach.
+ */
+export interface DeclarationTrustPolicy {
+    /**
+     * Hosts whose declarations this deployment accepts. An empty list with
+     * `allowAnyHttpsHost: false` accepts nothing, which is the safe default for
+     * a deployment that has not configured trust yet.
+     */
+    trustedHosts?: string[];
+    /** Opt in to accepting any HTTPS-reachable declaration host. */
+    allowAnyHttpsHost?: boolean;
+    /**
+     * Permit plain HTTP and private addresses. Test and loopback-development
+     * only — never in a deployment reachable from a network.
+     */
+    allowInsecureForTesting?: boolean;
+}
+/** Validate one URL in the chain. Applied to the origin URL and every hop. */
+export declare function checkDeclarationUrl(raw: string, policy: DeclarationTrustPolicy): DeclarationFailure | null;
+/**
+ * Project a normative §5 `SourceDeclaration` onto the internal snapshot shape.
+ *
+ * Returns the document unchanged when it is already in the internal shape, so
+ * existing private fixtures keep working — this is a compatibility adapter,
+ * not a redefinition of either format.
+ *
+ * The projection is deliberately narrow:
+ *   - `source.id` / `source.kind` → `source_id` / `source_kind`
+ *   - `declaration_version`       → `version`
+ *   - per stream, `schema.properties` keys → `fields`, and `schema.required`
+ *     → `required_fields`
+ *
+ * Deriving fields from the JSON Schema is the substantive part. The internal
+ * model wants a flat allowlist because §6 field selection and §8 projection
+ * operate on top-level names; the normative model carries a real schema
+ * because a declaration must describe record shape, not just name it. Reading
+ * `properties` keys is the honest projection of one onto the other, and
+ * `required` is exactly the per-stream consent floor §6 already calls for.
+ *
+ * Nothing here validates the normative document beyond what the projection
+ * needs — the checks that follow do that, and they run on the projected form
+ * so one code path enforces both.
+ */
+/**
+ * The source id a declaration document claims, in either shape.
+ *
+ * A caller that needs the id *before* parsing — a deployment loader keying
+ * retention by source, say — would otherwise have to reach into the document
+ * itself and pick a field. That is how the boot path came to accept only the
+ * internal flat `source_id` and silently skip every normative document, which
+ * left the AS unmounted with nothing but a warning to say why.
+ *
+ * Reading the shape is this module's job, so the question is answered here
+ * once. Returns null when neither shape carries a usable id; `parseDeclaration`
+ * remains the authority on whether the document is actually valid.
+ */
+export declare function declaredSourceId(body: string): string | null;
+export declare function computeDeclarationDigest(body: string): string;
+/**
+ * Parse and structurally validate a declaration document.
+ *
+ * Validates the embedded stream schemas enough that resolution can rely on
+ * them: every stream needs a name, a field list, and a primary key, and its
+ * `required_fields` must be a subset of its declared fields — otherwise the
+ * per-stream consent floor would name fields the schema does not have.
+ */
+export declare function parseDeclaration(body: string, expectedSourceId: string, expectedDigest?: string): DeclarationResult;
+/** Injected so tests exercise the bounds without real network access. */
+export type DeclarationFetcher = (url: string, init: {
+    redirect: "manual";
+    signal: AbortSignal;
+}) => Promise<Response>;
+/**
+ * Retrieve one declaration under the bounded rules, then parse and digest it.
+ *
+ * Redirects are followed manually so each hop can be re-validated. This is the
+ * difference between a fence and a formality: `fetch`'s automatic redirect
+ * following would validate only the URL we started with.
+ */
+export declare function retrieveDeclaration(url: string, expectedSourceId: string, policy: DeclarationTrustPolicy, options?: {
+    fetcher?: DeclarationFetcher;
+    expectedDigest?: string;
+}): Promise<DeclarationResult>;
+//# sourceMappingURL=declaration.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"declaration.d.ts","sourceRoot":"","sources":["../../src/pdpp/declaration.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAIH,OAAO,KAAK,EACV,mBAAmB,EAGpB,MAAM,YAAY,CAAC;AAEpB,eAAO,MAAM,qBAAqB,QAAa,CAAC;AAChD,eAAO,MAAM,aAAa,IAAI,CAAC;AAC/B,eAAO,MAAM,4BAA4B,OAAQ,CAAC;AAElD,MAAM,MAAM,sBAAsB,GAC9B,iBAAiB,GACjB,iBAAiB,GACjB,oBAAoB,GACpB,WAAW,GACX,cAAc,GACd,kBAAkB,GAClB,iBAAiB,GACjB,oBAAoB,GACpB,kBAAkB,GAClB,0BAA0B,GAC1B,qBAAqB,CAAC;AAE1B,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,sBAAsB,CAAC;IAC7B,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,MAAM,iBAAiB,GACzB;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,QAAQ,EAAE,mBAAmB,CAAA;CAAE,GAC3C;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,OAAO,EAAE,kBAAkB,CAAA;CAAE,CAAC;AAE/C;;;GAGG;AACH,MAAM,WAAW,sBAAsB;IACrC;;;;OAIG;IACH,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB,gEAAgE;IAChE,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B;;;OAGG;IACH,uBAAuB,CAAC,EAAE,OAAO,CAAC;CACnC;AAuCD,8EAA8E;AAC9E,wBAAgB,mBAAmB,CACjC,GAAG,EAAE,MAAM,EACX,MAAM,EAAE,sBAAsB,GAC7B,kBAAkB,GAAG,IAAI,CAuC3B;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH;;;;;;;;;;;;GAYG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAe5D;AAmOD,wBAAgB,wBAAwB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAE7D;AAgCD;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,MAAM,EACZ,gBAAgB,EAAE,MAAM,EACxB,cAAc,CAAC,EAAE,MAAM,GACtB,iBAAiB,CA6VnB;AA0CD,yEAAyE;AACzE,MAAM,MAAM,kBAAkB,GAAG,CAC/B,GAAG,EAAE,MAAM,EACX,IAAI,EAAE;IAAE,QAAQ,EAAE,QAAQ,CAAC;IAAC,MAAM,EAAE,WAAW,CAAA;CAAE,KAC9C,OAAO,CAAC,QAAQ,CAAC,CAAC;AAEvB;;;;;;GAMG;AACH,wBAAsB,mBAAmB,CACvC,GAAG,EAAE,MAAM,EACX,gBAAgB,EAAE,MAAM,EACxB,MAAM,EAAE,sBAAsB,EAC9B,OAAO,GAAE;IAAE,OAAO,CAAC,EAAE,kBAAkB,CAAC;IAAC,cAAc,CAAC,EAAE,MAAM,CAAA;CAAO,GACtE,OAAO,CAAC,iBAAiB,CAAC,CA+F5B"}