@opendatalabs/personal-server-ts-core 0.0.1-canary.00328bf

package/dist/pdpp/client-metadata.d.ts

@@ -0,0 +1,95 @@
+/**
+ * PDPP Core §6 requester-identity resolution.
+ *
+ * Two things the spec insists on keeping apart, and which are easy to conflate:
+ *
+ *   - **Verified domain control** means the AS retrieved this client's metadata
+ *     from the client_id URL over HTTPS and the document identified the same
+ *     client. It says the operator of that domain published this metadata. It
+ *     says nothing about the client's conduct or data practices.
+ *   - **App approval** means a local registration or trust-registry admission
+ *     decision — someone actually vetted the client.
+ *
+ * §6 obligation 5 requires the first to be rendered as a *named domain*
+ * ("Verified domain: example.com"), never as an unqualified "Verified app".
+ * `RequesterIdentity` therefore carries them as two separate fields, so a
+ * consent surface cannot render one as the other by accident.
+ */
+import type { RequesterIdentity } from "./review.js";
+import type { ClientDisplay } from "./types.js";
+/** Metadata the deployment holds locally, or a trust registry supplied. */
+export interface RegisteredClientMetadata {
+    client_id: string;
+    display: ClientDisplay;
+    /** True only when an admission decision was actually made. */
+    approved: boolean;
+}
+/**
+ * A client ID metadata document retrieved from the client_id URL.
+ *
+ * §6: the document is *valid* only when it was retrieved over HTTPS from the
+ * client_id URL itself and the `client_id` inside it is identical to that URL.
+ * That last check is what stops a document claiming to be a different client.
+ */
+export interface ClientIdMetadataDocument {
+    /** The URL the document was retrieved from. */
+    retrieved_from: string;
+    /** The client_id the document asserts. */
+    client_id: string;
+    /**
+     * Optional: a document may validly declare redirect_uris and no name. An
+     * absent name must stay absent rather than become `{ name: "" }`, which
+     * would outrank inline metadata in §6 precedence and render a blank
+     * requester on the consent surface.
+     */
+    display?: ClientDisplay;
+    /** Whether retrieval used HTTPS. */
+    https: boolean;
+}
+export interface ResolveRequesterInput {
+    client_id: string;
+    /** Highest precedence: local registration or trust registry. */
+    registered?: RegisteredClientMetadata;
+    /** Validated binding metadata, when the binding supplied one. */
+    document?: ClientIdMetadataDocument;
+    /** Lowest precedence: the client's own inline assertion. */
+    inline?: ClientDisplay;
+}
+/**
+ * Validate a client ID metadata document per §6.
+ *
+ * Returns the verified domain when all three conditions hold, otherwise null.
+ * A null result is not a rejection of the client — §6's interoperability
+ * obligation forbids rejecting a valid document merely for being
+ * unpreregistered, and a document that fails validation just means we fall
+ * through to a lower-precedence metadata source.
+ */
+export declare function verifyClientIdDocument(doc: ClientIdMetadataDocument): {
+    verifiedDomain: string;
+} | null;
+/**
+ * Resolve requester identity under §6's precedence:
+ *
+ *   local registration / trust registry
+ *     > validated software statement (not supported in this build)
+ *     > validated binding metadata (the client ID metadata document)
+ *     > inline `client_display`
+ *     > `client_id` fallback
+ *
+ * The display name always resolves to something: §6 obligation 2 requires the
+ * AS to display `client_id` when no name is available, so the consent surface
+ * is never left with nothing to render.
+ */
+export declare function resolveRequesterIdentity(input: ResolveRequesterInput): RequesterIdentity;
+/**
+ * Whether a client-supplied remote logo may be rendered directly.
+ *
+ * §6 obligation 6: `logo_uri` is untrusted content. An unverified client's
+ * remote logo must not be fetched into the consent UI — the surface generates
+ * a monogram from the display name instead. Proxied-and-approved assets are a
+ * deployment concern the caller signals explicitly.
+ */
+export declare function mayRenderRemoteLogo(identity: RequesterIdentity, options?: {
+    assetProxiedAndApproved?: boolean;
+}): boolean;
+//# sourceMappingURL=client-metadata.d.ts.map

package/dist/pdpp/client-metadata.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client-metadata.d.ts","sourceRoot":"","sources":["../../src/pdpp/client-metadata.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AACrD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAEhD,2EAA2E;AAC3E,MAAM,WAAW,wBAAwB;IACvC,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,aAAa,CAAC;IACvB,8DAA8D;IAC9D,QAAQ,EAAE,OAAO,CAAC;CACnB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,wBAAwB;IACvC,+CAA+C;IAC/C,cAAc,EAAE,MAAM,CAAC;IACvB,0CAA0C;IAC1C,SAAS,EAAE,MAAM,CAAC;IAClB;;;;;OAKG;IACH,OAAO,CAAC,EAAE,aAAa,CAAC;IACxB,oCAAoC;IACpC,KAAK,EAAE,OAAO,CAAC;CAChB;AAED,MAAM,WAAW,qBAAqB;IACpC,SAAS,EAAE,MAAM,CAAC;IAClB,gEAAgE;IAChE,UAAU,CAAC,EAAE,wBAAwB,CAAC;IACtC,iEAAiE;IACjE,QAAQ,CAAC,EAAE,wBAAwB,CAAC;IACpC,4DAA4D;IAC5D,MAAM,CAAC,EAAE,aAAa,CAAC;CACxB;AAED;;;;;;;;GAQG;AACH,wBAAgB,sBAAsB,CACpC,GAAG,EAAE,wBAAwB,GAC5B;IAAE,cAAc,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAsBnC;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,wBAAwB,CACtC,KAAK,EAAE,qBAAqB,GAC3B,iBAAiB,CAoBnB;AAED;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CACjC,QAAQ,EAAE,iBAAiB,EAC3B,OAAO,GAAE;IAAE,uBAAuB,CAAC,EAAE,OAAO,CAAA;CAAO,GAClD,OAAO,CAGT"}

package/dist/pdpp/client-metadata.js

@@ -0,0 +1,96 @@
+/**
+ * PDPP Core §6 requester-identity resolution.
+ *
+ * Two things the spec insists on keeping apart, and which are easy to conflate:
+ *
+ *   - **Verified domain control** means the AS retrieved this client's metadata
+ *     from the client_id URL over HTTPS and the document identified the same
+ *     client. It says the operator of that domain published this metadata. It
+ *     says nothing about the client's conduct or data practices.
+ *   - **App approval** means a local registration or trust-registry admission
+ *     decision — someone actually vetted the client.
+ *
+ * §6 obligation 5 requires the first to be rendered as a *named domain*
+ * ("Verified domain: example.com"), never as an unqualified "Verified app".
+ * `RequesterIdentity` therefore carries them as two separate fields, so a
+ * consent surface cannot render one as the other by accident.
+ */
+/**
+ * Validate a client ID metadata document per §6.
+ *
+ * Returns the verified domain when all three conditions hold, otherwise null.
+ * A null result is not a rejection of the client — §6's interoperability
+ * obligation forbids rejecting a valid document merely for being
+ * unpreregistered, and a document that fails validation just means we fall
+ * through to a lower-precedence metadata source.
+ */
+export function verifyClientIdDocument(doc) {
+    if (!doc.https)
+        return null;
+    let retrievedUrl;
+    try {
+        retrievedUrl = new URL(doc.retrieved_from);
+    }
+    catch {
+        return null;
+    }
+    if (retrievedUrl.protocol !== "https:")
+        return null;
+    // The identity check: the document's client_id must be the URL it came from.
+    // Compared as URLs so a trailing-slash difference is not a false negative.
+    let assertedUrl;
+    try {
+        assertedUrl = new URL(doc.client_id);
+    }
+    catch {
+        return null;
+    }
+    if (assertedUrl.toString() !== retrievedUrl.toString())
+        return null;
+    return { verifiedDomain: retrievedUrl.hostname };
+}
+/**
+ * Resolve requester identity under §6's precedence:
+ *
+ *   local registration / trust registry
+ *     > validated software statement (not supported in this build)
+ *     > validated binding metadata (the client ID metadata document)
+ *     > inline `client_display`
+ *     > `client_id` fallback
+ *
+ * The display name always resolves to something: §6 obligation 2 requires the
+ * AS to display `client_id` when no name is available, so the consent surface
+ * is never left with nothing to render.
+ */
+export function resolveRequesterIdentity(input) {
+    const verification = input.document
+        ? verifyClientIdDocument(input.document)
+        : null;
+    // Precedence order, highest first.
+    const display = input.registered?.display ??
+        (verification ? input.document?.display : undefined) ??
+        input.inline;
+    return {
+        client_id: input.client_id,
+        display_name: display?.name ?? input.client_id,
+        ...(display && { display }),
+        // Named, not asserted as blanket verification.
+        ...(verification && { verified_domain: verification.verifiedDomain }),
+        // Only a real admission decision counts. Domain control is not approval.
+        app_approved: input.registered?.approved ?? false,
+    };
+}
+/**
+ * Whether a client-supplied remote logo may be rendered directly.
+ *
+ * §6 obligation 6: `logo_uri` is untrusted content. An unverified client's
+ * remote logo must not be fetched into the consent UI — the surface generates
+ * a monogram from the display name instead. Proxied-and-approved assets are a
+ * deployment concern the caller signals explicitly.
+ */
+export function mayRenderRemoteLogo(identity, options = {}) {
+    if (options.assetProxiedAndApproved === true)
+        return true;
+    return identity.app_approved || identity.verified_domain !== undefined;
+}
+//# sourceMappingURL=client-metadata.js.map

package/dist/pdpp/client-metadata.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client-metadata.js","sourceRoot":"","sources":["../../src/pdpp/client-metadata.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AA8CH;;;;;;;;GAQG;AACH,MAAM,UAAU,sBAAsB,CACpC,GAA6B;IAE7B,IAAI,CAAC,GAAG,CAAC,KAAK;QAAE,OAAO,IAAI,CAAC;IAE5B,IAAI,YAAiB,CAAC;IACtB,IAAI,CAAC;QACH,YAAY,GAAG,IAAI,GAAG,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC;IAC7C,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;IACD,IAAI,YAAY,CAAC,QAAQ,KAAK,QAAQ;QAAE,OAAO,IAAI,CAAC;IAEpD,6EAA6E;IAC7E,2EAA2E;IAC3E,IAAI,WAAgB,CAAC;IACrB,IAAI,CAAC;QACH,WAAW,GAAG,IAAI,GAAG,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;IACvC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;IACD,IAAI,WAAW,CAAC,QAAQ,EAAE,KAAK,YAAY,CAAC,QAAQ,EAAE;QAAE,OAAO,IAAI,CAAC;IAEpE,OAAO,EAAE,cAAc,EAAE,YAAY,CAAC,QAAQ,EAAE,CAAC;AACnD,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,wBAAwB,CACtC,KAA4B;IAE5B,MAAM,YAAY,GAAG,KAAK,CAAC,QAAQ;QACjC,CAAC,CAAC,sBAAsB,CAAC,KAAK,CAAC,QAAQ,CAAC;QACxC,CAAC,CAAC,IAAI,CAAC;IAET,mCAAmC;IACnC,MAAM,OAAO,GACX,KAAK,CAAC,UAAU,EAAE,OAAO;QACzB,CAAC,YAAY,CAAC,CAAC,CAAC,KAAK,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC,CAAC,SAAS,CAAC;QACpD,KAAK,CAAC,MAAM,CAAC;IAEf,OAAO;QACL,SAAS,EAAE,KAAK,CAAC,SAAS;QAC1B,YAAY,EAAE,OAAO,EAAE,IAAI,IAAI,KAAK,CAAC,SAAS;QAC9C,GAAG,CAAC,OAAO,IAAI,EAAE,OAAO,EAAE,CAAC;QAC3B,+CAA+C;QAC/C,GAAG,CAAC,YAAY,IAAI,EAAE,eAAe,EAAE,YAAY,CAAC,cAAc,EAAE,CAAC;QACrE,yEAAyE;QACzE,YAAY,EAAE,KAAK,CAAC,UAAU,EAAE,QAAQ,IAAI,KAAK;KAClD,CAAC;AACJ,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,mBAAmB,CACjC,QAA2B,EAC3B,UAAiD,EAAE;IAEnD,IAAI,OAAO,CAAC,uBAAuB,KAAK,IAAI;QAAE,OAAO,IAAI,CAAC;IAC1D,OAAO,QAAQ,CAAC,YAAY,IAAI,QAAQ,CAAC,eAAe,KAAK,SAAS,CAAC;AACzE,CAAC"}

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" | "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,EAAE,mBAAmB,EAAc,MAAM,YAAY,CAAC;AAElE,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,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;AA4CD,wBAAgB,wBAAwB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAE7D;AAWD;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,MAAM,EACZ,gBAAgB,EAAE,MAAM,EACxB,cAAc,CAAC,EAAE,MAAM,GACtB,iBAAiB,CA8OnB;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"}