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

package/dist/pdpp/store.d.ts

@@ -0,0 +1,228 @@
+/**
+ * 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;
+    ownerSourceId: string | null;
+    ownerInstanceIds: string[] | null;
+    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;
+    /**
+     * Persist an issued grant and its authorization code as one durable unit.
+     *
+     * An owner approval produces exactly one grant and exactly one redeemable
+     * code; there is no meaningful state where one exists without the other.
+     * Without this, a failure between the two inserts (disk full, process
+     * kill) could leave a grant with no code ever issued for it — and, worse,
+     * strand the caller's in-memory approval state with nothing durable to
+     * show for it. Wrapping both in one transaction makes the local write
+     * atomic: it either lands completely or not at all, so a caller can retry
+     * the same approval decision safely on failure.
+     */
+    insertGrantWithAuthCode(input: {
+        grant: Grant;
+        subjectId: string;
+        reviewDigest: string;
+        consentEvidence?: unknown;
+        code: string;
+        authCode: AuthCodeRecord;
+    }): 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;
+        ownerSourceId?: string | null;
+        ownerInstanceIds?: string[] | null;
+        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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"}