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

package/dist/pdpp/selection.js

@@ -0,0 +1,211 @@
+/**
+ * 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 { PDPP_DATA_ACCESS_TYPE, } from "./types.js";
+function fail(code, message) {
+    return { ok: false, failure: { code, message } };
+}
+/**
+ * Canonical key strings: a plain string for a simple key, a minified JSON
+ * array for a compound key (§6 `resources`). We validate arity and type
+ * against the declaration's `primary_key` here so an unsatisfiable resource
+ * list is rejected at issuance rather than silently matching nothing at the RS.
+ */
+function validateResourceKey(raw, primaryKey) {
+    if (primaryKey.length <= 1) {
+        // A simple key is a plain string. A JSON array here is an arity error.
+        if (raw.startsWith("[")) {
+            return "expected a simple key string, got a compound key array";
+        }
+        return raw.length > 0 ? null : "resource key must not be empty";
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return "compound resource key must be a minified JSON array";
+    }
+    if (!Array.isArray(parsed)) {
+        return "compound resource key must be a JSON array";
+    }
+    if (parsed.length !== primaryKey.length) {
+        return `compound resource key has ${parsed.length} parts, declaration primary_key has ${primaryKey.length}`;
+    }
+    if (!parsed.every((part) => typeof part === "string")) {
+        return "compound resource key parts must be strings";
+    }
+    return null;
+}
+function validateStreamRequest(stream, snapshot) {
+    // A wildcard is checked by the caller (it must be the sole entry) and
+    // expands during resolution, so there is no declared stream to match yet.
+    if (stream.name === "*") {
+        if (stream.view !== undefined) {
+            return fail("unsupported_selection_parameter", "view cannot be combined with a wildcard stream selection");
+        }
+        return { ok: true };
+    }
+    const declared = snapshot.streams.find((s) => s.name === stream.name);
+    if (!declared) {
+        return fail("unknown_stream", `stream '${stream.name}' is not declared by the retained snapshot`);
+    }
+    if (stream.view !== undefined && stream.fields !== undefined) {
+        return fail("invalid_request", `stream '${stream.name}' specifies both view and fields, which are mutually exclusive`);
+    }
+    if (stream.view !== undefined) {
+        const view = snapshot.views?.find((v) => v.name === stream.view);
+        if (!view) {
+            return fail("unknown_view", `view '${stream.view}' is not defined for this source`);
+        }
+        // §9 AS item 12: a view naming a field absent from the retained schema is
+        // not resolvable, and we reject rather than silently dropping the field.
+        const absent = view.fields.filter((f) => !declared.fields.includes(f));
+        if (absent.length > 0) {
+            return fail("unknown_field", `view '${stream.view}' names fields absent from stream '${stream.name}': ${absent.join(", ")}`);
+        }
+    }
+    if (stream.fields !== undefined) {
+        if (stream.fields.length === 0) {
+            return fail("invalid_request", `stream '${stream.name}' specifies an empty fields list`);
+        }
+        const absent = stream.fields.filter((f) => !declared.fields.includes(f));
+        if (absent.length > 0) {
+            return fail("unknown_field", `stream '${stream.name}' requests fields absent from the retained schema: ${absent.join(", ")}`);
+        }
+    }
+    if (stream.time_range !== undefined) {
+        // §6: the declaration's consent_time_field is the authoritative signal
+        // that a stream is time-range-capable. No field, no time_range.
+        if (!declared.consent_time_field) {
+            return fail("unsupported_selection_parameter", `stream '${stream.name}' declares no consent_time_field and cannot accept time_range`);
+        }
+        const { since, until } = stream.time_range;
+        if (since === undefined && until === undefined) {
+            return fail("invalid_request", `stream '${stream.name}' has an empty time_range`);
+        }
+        for (const [label, value] of [
+            ["since", since],
+            ["until", until],
+        ]) {
+            if (value !== undefined && Number.isNaN(Date.parse(value))) {
+                return fail("invalid_request", `stream '${stream.name}' time_range.${label} is not a valid ISO 8601 instant`);
+            }
+        }
+        if (since !== undefined && until !== undefined) {
+            if (Date.parse(since) >= Date.parse(until)) {
+                return fail("invalid_request", `stream '${stream.name}' time_range.since must precede time_range.until`);
+            }
+        }
+    }
+    if (stream.resources !== undefined) {
+        if (stream.resources.length === 0) {
+            return fail("invalid_request", `stream '${stream.name}' specifies an empty resources list`);
+        }
+        for (const raw of stream.resources) {
+            const problem = validateResourceKey(raw, declared.primary_key);
+            if (problem) {
+                return fail("invalid_resource_key", `stream '${stream.name}' resource '${raw}': ${problem}`);
+            }
+        }
+    }
+    return { ok: true };
+}
+/**
+ * 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 function validateSelectionRequest(request, snapshot) {
+    if (request.type !== PDPP_DATA_ACCESS_TYPE) {
+        return fail("invalid_request", `authorization detail type must be ${PDPP_DATA_ACCESS_TYPE}`);
+    }
+    if (request.source.id !== snapshot.source_id) {
+        return fail("invalid_request", "request source.id does not match the retained declaration snapshot");
+    }
+    // §6: the purpose code must be a syntactically valid absolute URI, and that
+    // is the only syntactic gate. §9 AS item 6 forbids rejecting a code merely
+    // for being absent from the registry — an unregistered code renders from its
+    // description or raw URI instead.
+    if (!isAbsoluteUri(request.purpose_code)) {
+        return fail("invalid_request", "purpose_code must be an absolute URI");
+    }
+    if (request.access_mode !== "single_use" &&
+        request.access_mode !== "continuous") {
+        return fail("invalid_request", "access_mode must be single_use or continuous");
+    }
+    if (request.retention !== undefined) {
+        const { on_expiry } = request.retention;
+        if (on_expiry !== "delete" && on_expiry !== "anonymize") {
+            // `archive` was dropped in v0.1 and is the likely wrong value here.
+            return fail("invalid_request", "retention.on_expiry must be delete or anonymize");
+        }
+    }
+    const hasStreams = request.streams !== undefined;
+    const hasPreset = request.selection_preset !== undefined;
+    if (hasStreams === hasPreset) {
+        // Both or neither. Deliberately one message for both cases: the failure
+        // is about the pair, and distinguishing them tells a probing client which
+        // half the server accepted.
+        return fail("source_validation_failed", "exactly one of streams or selection_preset is required");
+    }
+    if (hasPreset) {
+        const preset = snapshot.selection_presets?.find((p) => p.name === request.selection_preset);
+        if (!preset) {
+            return fail("unknown_preset", `selection preset '${request.selection_preset}' is not defined by the retained snapshot`);
+        }
+        // The preset's own streams still have to be expressible against the
+        // snapshot; a declaration that ships a preset naming a dropped stream is
+        // invalid and we would rather fail here than resolve an empty grant.
+        for (const stream of preset.streams) {
+            const result = validateStreamRequest(stream, snapshot);
+            if (!result.ok)
+                return result;
+        }
+        return { ok: true };
+    }
+    const streams = request.streams ?? [];
+    if (streams.length === 0) {
+        return fail("invalid_request", "streams must not be empty");
+    }
+    const wildcards = streams.filter((s) => s.name === "*");
+    if (wildcards.length > 0 && streams.length > 1) {
+        return fail("invalid_request", "a wildcard stream entry must be the only entry in streams");
+    }
+    const seen = new Set();
+    for (const stream of streams) {
+        if (seen.has(stream.name)) {
+            return fail("invalid_request", `stream '${stream.name}' appears more than once`);
+        }
+        seen.add(stream.name);
+        const result = validateStreamRequest(stream, snapshot);
+        if (!result.ok)
+            return result;
+    }
+    return { ok: true };
+}
+function isAbsoluteUri(value) {
+    try {
+        // URL rejects relative references, which is exactly the check we want.
+        new URL(value);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+//# sourceMappingURL=selection.js.map

package/dist/pdpp/selection.js.map

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

package/dist/pdpp/store.d.ts

@@ -0,0 +1,204 @@
+/**
+ * Persisted PDPP authorization state: declarations, grants, authorization
+ * codes, and the token/refresh-family graph.
+ *
+ * SQLite via better-sqlite3, matching `../storage/index/schema.ts`. The choice
+ * is not incidental: three requirements in §7/§9 are atomicity requirements,
+ * and a JSON file (the pattern `server/src/token-store.ts` uses for session
+ * tokens) cannot express them without a lock of its own.
+ *
+ *   - §9 AS item 10: a `single_use` grant is consumed *atomically* with first
+ *     client-token issuance.
+ *   - §9 AS item 19: an authorization code is consumed *atomically* on first
+ *     successful redemption; every later redemption fails.
+ *   - §9 AS item 20: refresh reuse revokes the family and all linked tokens.
+ *
+ * Each is implemented as a conditional UPDATE inside a transaction, where the
+ * WHERE clause carries the precondition. `changes === 0` then means "someone
+ * else won the race", which is the only correct answer — checking state and
+ * then writing it would be exactly the TOCTOU bug these items exist to close.
+ *
+ * Tokens are stored as SHA-256 hashes, never plaintext, so a store dump does
+ * not yield usable credentials (§10 "Token security").
+ */
+import Database from "better-sqlite3";
+import type { DeclarationSnapshot, Grant, GrantStatus, PdppTokenKind } from "./types.js";
+/**
+ * Persisted-state contract version. §7 "Version layering" and §9 AS item 21
+ * require the reader to reject state it cannot validate against a supported
+ * contract, and forbid reconstructing missing facts from current config.
+ */
+export declare const PDPP_AUTH_STATE_VERSION = 1;
+export declare class UnsupportedAuthStateError extends Error {
+    readonly foundVersion: number;
+    readonly supportedVersion: number;
+    constructor(foundVersion: number, supportedVersion?: number);
+}
+export declare function hashToken(token: string): string;
+export declare function newOpaqueToken(prefix: string): string;
+export interface StoredGrant {
+    grant: Grant;
+    subjectId: string;
+    clientId: string;
+    reviewDigest: string;
+    issuedAt: string;
+    expiresAt: string | null;
+    revokedAt: string | null;
+    consumedAt: string | null;
+}
+export interface AccessTokenRecord {
+    tokenHash: string;
+    grantId: string | null;
+    subjectId: string;
+    clientId: string | null;
+    tokenKind: PdppTokenKind;
+    familyId: string | null;
+    issuedAt: string;
+    expiresAt: string | null;
+    revokedAt: string | null;
+}
+export interface AuthCodeRecord {
+    grantId: string;
+    clientId: string;
+    redirectUri: string;
+    codeChallenge: string | null;
+    codeChallengeMethod: string | null;
+    expiresAt: string;
+}
+/**
+ * Open (and if needed create) the PDPP authorization store.
+ *
+ * Rejects a store whose persisted version this build cannot validate, before
+ * any caller reads authorization facts out of it. That is §9 AS item 21: the
+ * failure is loud and up front, not a silently-degraded read path.
+ */
+export declare function openPdppAuthStore(dbPath: string): PdppAuthStore;
+export declare class PdppAuthStore {
+    private readonly db;
+    constructor(db: Database.Database);
+    close(): void;
+    /**
+     * Retain a declaration snapshot, and the exact bytes it was parsed from.
+     *
+     * Idempotent per (source_id, version): a re-retrieval of the same revision
+     * must not disturb the retained facts an issued grant points at, so the
+     * first snapshot wins and is never overwritten.
+     *
+     * The one exception is BACKFILLING `document`. A deployment that retained a
+     * version before this column existed has a NULL document, and a plain
+     * `DO NOTHING` would leave it NULL forever — the existing row would keep
+     * winning on every restart, so the digest would stay unverifiable until the
+     * declaration version happened to change. `COALESCE` fills it in once and
+     * then never changes it, so backfill happens exactly when it is missing and
+     * the retained bytes remain immutable thereafter.
+     */
+    retainDeclaration(snapshot: DeclarationSnapshot, document?: string): void;
+    getDeclaration(sourceId: string, version: string): DeclarationSnapshot | null;
+    /**
+     * The exact retrieved bytes a retained declaration was parsed from.
+     *
+     * Returns null when this row predates the `document` column and has not been
+     * backfilled. A caller MUST treat null as "cannot verify from the store",
+     * never as "verified" — the whole point of this accessor is that re-digesting
+     * `snapshot_json` would silently produce a different value than the retained
+     * `digest`.
+     */
+    getDeclarationDocument(sourceId: string, version: string): string | null;
+    insertGrant(input: {
+        grant: Grant;
+        subjectId: string;
+        reviewDigest: string;
+        /** Normalized bound client claims, retained as consent evidence only. */
+        consentEvidence?: unknown;
+    }): void;
+    getGrant(grantId: string): StoredGrant | null;
+    listGrantsForSubject(subjectId: string): StoredGrant[];
+    /**
+     * Grant lifecycle (§9 AS item 8). Revoked beats expired: once an owner
+     * revokes, that is the fact worth reporting, and it does not become
+     * "expired" later just because the clock passed.
+     */
+    grantStatus(stored: StoredGrant, now?: Date): GrantStatus;
+    /**
+     * Revoke a grant and everything linked to it, in one transaction.
+     *
+     * §2 of the delivery scope: the AS marks the grant and every linked token
+     * family inactive *immediately*. Doing this in one transaction means there
+     * is no window where the grant reads revoked but a linked access token still
+     * introspects active.
+     *
+     * Returns false if the grant does not exist or was already revoked, so a
+     * double revoke is not reported as a fresh one.
+     */
+    revokeGrant(grantId: string, now?: Date): boolean;
+    insertAuthCode(code: string, record: AuthCodeRecord): void;
+    /**
+     * Consume an authorization code atomically (§9 AS item 19).
+     *
+     * The `redeemed_at IS NULL` predicate lives in the UPDATE, so two concurrent
+     * redemptions of the same code cannot both see it unredeemed. Exactly one
+     * gets `changes === 1`; the loser gets null and the caller returns
+     * `invalid_grant`. An expired code fails the same way, and a replayed code
+     * never issues a second token.
+     */
+    consumeAuthCode(code: string, now?: Date): AuthCodeRecord | null;
+    /**
+     * Consume a `single_use` grant atomically with the first client access token
+     * (§9 AS item 10 / §7 access modes).
+     *
+     * Both the consumption and the token insert happen in one transaction with
+     * the precondition in the UPDATE's WHERE clause, so a second concurrent
+     * issuance attempt finds `changes === 0` and issues nothing. A `continuous`
+     * grant skips the consume step and may issue repeatedly.
+     *
+     * Returns false when the grant was already consumed — the caller maps that
+     * to `invalid_grant`. Note §7: the RS still honors tokens already issued
+     * against a consumed grant until they expire or are revoked; consumption
+     * blocks *new* token issuance, not use of the existing token.
+     */
+    issueAccessToken(input: {
+        token: string;
+        grantId: string | null;
+        subjectId: string;
+        clientId: string | null;
+        tokenKind: PdppTokenKind;
+        familyId?: string | null;
+        expiresAt: string | null;
+        /** Enforce single-use consumption as part of this issuance. */
+        consumeSingleUse: boolean;
+        now?: Date;
+    }): boolean;
+    getAccessToken(token: string): AccessTokenRecord | null;
+    createRefreshFamily(grantId: string): string;
+    insertRefreshToken(token: string, familyId: string, now?: Date): void;
+    /**
+     * Rotate a refresh token, detecting reuse (§9 AS item 20).
+     *
+     * Three outcomes:
+     *   - `{ ok: true }`: the presented token was current; it is superseded and
+     *     the caller issues a replacement in the same family.
+     *   - `{ ok: false, reason: "reuse_detected" }`: the token was already
+     *     superseded. The family and every family-linked access token are
+     *     revoked here, atomically, before returning. The caller returns
+     *     `invalid_grant` and the client must obtain fresh authorization.
+     *   - `{ ok: false, reason: "unknown" | "family_revoked" }`: nothing to
+     *     rotate.
+     *
+     * Reuse revoking the family is the whole point: an attacker who replays a
+     * stolen refresh token and a legitimate client who replays after a dropped
+     * response are indistinguishable, so the safe response is to kill both and
+     * force a fresh grant-backed authorization.
+     */
+    rotateRefreshToken(presented: string, now?: Date): {
+        ok: true;
+        familyId: string;
+        grantId: string;
+    } | {
+        ok: false;
+        reason: "unknown" | "reuse_detected" | "family_revoked";
+    };
+    /** Revoke one access token. Returns false if unknown or already revoked. */
+    revokeAccessToken(token: string, now?: Date): boolean;
+    isFamilyRevoked(familyId: string): boolean;
+}
+//# sourceMappingURL=store.d.ts.map

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

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