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

package/dist/pdpp/approval.d.ts

@@ -0,0 +1,271 @@
+/**
+ * Authorization sessions and authenticated owner approval.
+ *
+ * This is the module that decides whether a consent decision is real. The
+ * threat it exists to stop is an approval that looks right — correct session,
+ * correct review digest, arriving from the first-party consent UI — but that
+ * no authenticated owner actually made.
+ *
+ * The rule: **affiliation is not authentication.** The AS does not accept an
+ * approval because it came from an allowlisted origin, a first-party console,
+ * a shared UI/server secret, or a signed assertion from the consent broker
+ * saying "the owner agreed". Each of those authenticates a *channel* or
+ * delegates the decision to a browser-reachable component; compromise it and
+ * it mints approvals for any subject. Instead, the owner authenticates to the
+ * PS itself, and the resulting owner token — resolved through the same token
+ * service the RS uses — is what authorizes the decision. The consent UI
+ * forwards that token; it can never substitute for it.
+ *
+ * Two independent checks must both pass, and neither implies the other:
+ *
+ *   1. The caller presents an active token with `pdpp_token_kind: "owner"`
+ *      whose `subject_id` equals the session's subject. Possession of the
+ *      session id is not authority over it.
+ *   2. The presented `review_digest` matches a re-derivation over what is
+ *      about to be issued (§7 staleness). Authenticating the owner does not
+ *      excuse approving something other than what they reviewed.
+ */
+import { type ConsentReviewModel, type RequesterIdentity } from "./review.js";
+import { type ConsentEvidence } from "./issuance.js";
+import { type InstanceInventory, type OwnerChoices } from "./resolve.js";
+import type { PdppAuthStore } from "./store.js";
+import type { PdppTokenService } from "./tokens.js";
+import type { DeclarationSnapshot, Grant, OwnerConditions, RecipientTerms, SelectionRequest } from "./types.js";
+/** How long an owner has to act on a consent screen before it goes stale. */
+export declare const REVIEW_SESSION_TTL_SECONDS: number;
+export type SessionState = "pending" | "approved" | "denied";
+export interface AuthorizationSession {
+    session_id: string;
+    /** The subject this session belongs to. An approval must authenticate as this. */
+    subject_id: string;
+    request: SelectionRequest;
+    snapshot: DeclarationSnapshot;
+    requester: RequesterIdentity;
+    redirect_uri: string;
+    state_param?: string;
+    /** RFC 7636 challenge, carried to the authorization code minted on approval. */
+    code_challenge?: string;
+    code_challenge_method?: string;
+    expires_at: string;
+    status: SessionState;
+    /** AS-policy grant expiry carried into issuance. */
+    grant_expires_at?: string;
+    stream_descriptions?: Record<string, string>;
+    /** The owner's optional reason for denying. Never sent to the client. */
+    denial_reason?: string;
+}
+export type ApprovalFailureCode = 
+/** No owner token, an inactive one, a client token, or the wrong subject. */
+"unauthorized" | "session_not_found" | "stale_review" | "ai_training_consent_required"
+/** The session is already decided. Not a v0.2 refusal — see below. */
+ | "access_denied"
+/**
+ * v0.2: the owner's choices cannot satisfy the request's own requirements —
+ * a declined required stream, an unmet required minimum, or an approval with
+ * no stream left. PR #1 names `access_denied` as the OAuth error for this,
+ * but it is deliberately a *separate* Core code from the already-decided
+ * `access_denied` above: the two want different HTTP statuses and different
+ * consent-UI handling (adjust your choices vs. start over), and collapsing
+ * them changed the status of the existing session-state case.
+ */
+ | "selection_refused"
+/**
+ * v0.2: an owner condition on purpose or retention the recipient's authority
+ * does not cover. Separate from `selection_refused` because the resolution
+ * differs: the owner can adjust a selection themselves, but only the
+ * recipient can accept a term.
+ */
+ | "recipient_terms_unsupported" | "unsupported_instance_fan_in" | "invalid_request";
+export interface ApprovalFailure {
+    code: ApprovalFailureCode;
+    message: string;
+}
+export type ApprovalResult = {
+    ok: true;
+    grant: Grant;
+    consentEvidence: ConsentEvidence;
+} | {
+    ok: false;
+    failure: ApprovalFailure;
+};
+/**
+ * In-memory pending-session store. Sessions are short-lived and pre-decision,
+ * so they hold no issued authority — losing them on restart costs an owner a
+ * re-click, not a grant. Issued grants and tokens go to SQLite, where
+ * durability actually matters.
+ */
+export declare class AuthorizationSessionStore {
+    private readonly sessions;
+    create(input: {
+        subjectId: string;
+        request: SelectionRequest;
+        snapshot: DeclarationSnapshot;
+        requester: RequesterIdentity;
+        redirectUri: string;
+        stateParam?: string;
+        codeChallenge?: string;
+        codeChallengeMethod?: string;
+        grantExpiresAt?: string;
+        streamDescriptions?: Record<string, string>;
+        now?: Date;
+    }): AuthorizationSession;
+    get(sessionId: string): AuthorizationSession | null;
+    setStatus(sessionId: string, status: SessionState): void;
+    /**
+     * Retain the owner's reason for denying, beside the denial itself.
+     *
+     * Kept on the session rather than in the grant store because there is no
+     * grant: a denial produces no authorization, and the reason is the owner's
+     * note about a decision, not a term of one.
+     */
+    setDenialReason(sessionId: string, reason: string): void;
+}
+/**
+ * A stream the owner must pick an instance for before the review can resolve.
+ *
+ * §6 is strict that omitting `instance_ids` never means fan-in, so a stream
+ * with several eligible handles and none named is a decision only the owner
+ * can make. Surfacing the candidates as first-class review data is what turns
+ * that from a dead-end resolution failure into a consent step: the UI renders
+ * the choice, the owner picks, and the pick flows back through
+ * `instanceChoices` on the next review fetch and on approval.
+ */
+export interface InstanceChoice {
+    stream: string;
+    candidates: string[];
+}
+export interface ReviewFetchResult {
+    session_id: string;
+    /** Present only once every stream resolves. Absent while a choice is pending. */
+    review?: ConsentReviewModel;
+    /**
+     * Non-empty when the owner must choose instance handles before there is a
+     * decision to review. The UI collects these and re-fetches with the picks.
+     */
+    instance_choice_required?: InstanceChoice[];
+    expires_at: string;
+}
+/**
+ * Build the review an authenticated owner sees.
+ *
+ * Resolution runs here against current inventory, so the digest the owner is
+ * handed reflects the world as it is right now. If it changes before they
+ * approve, `approveAuthorization` will re-derive a different digest and reject.
+ */
+export declare function fetchReview(input: {
+    sessions: AuthorizationSessionStore;
+    tokens: PdppTokenService;
+    sessionId: string;
+    ownerToken: string | undefined;
+    inventory: InstanceInventory;
+    /** The owner's instance picks, keyed by stream, from a prior choice step. */
+    instanceChoices?: Record<string, string[]>;
+    /**
+     * The owner's v0.2 narrowing so far. The review re-resolves against it, so
+     * the surface always shows the *current* proposal and its digest — which is
+     * what the owner then approves. A narrowing that would refuse issuance
+     * surfaces here as a failure rather than at approval, so the owner learns
+     * their choice is incompatible while they can still change it.
+     */
+    ownerChoices?: OwnerChoices;
+    /** v0.2: conditions the owner attached beyond narrowing the data. */
+    ownerConditions?: OwnerConditions;
+    /** v0.2: standing terms the recipient authorized, when the AS tracks them. */
+    standingTerms?: RecipientTerms;
+    /**
+     * When given, the review lists this requesting client's other active
+     * grants for this owner, so the consent surface can say what is already
+     * shared. Approval itself is unaffected either way.
+     */
+    store?: PdppAuthStore;
+    /**
+     * Optional owner-token instance scope for `existing_grants`. When present,
+     * only grants wholly contained by this scope are included in the review.
+     */
+    existingGrantInstanceIds?: string[];
+    now?: Date;
+}): {
+    ok: true;
+    result: ReviewFetchResult;
+} | {
+    ok: false;
+    failure: ApprovalFailure;
+};
+/**
+ * Approve an authorization: authenticate the owner, then issue.
+ *
+ * Order is deliberate. Authentication runs before anything else, so an
+ * unauthenticated caller cannot learn from the error whether their digest was
+ * fresh — a spoofed approval with a perfectly valid digest gets the same
+ * `unauthorized` as one with a garbage digest.
+ *
+ * This function does not mark the session `"approved"` — it only decides
+ * whether the review is valid and computes what to issue. The session
+ * transitions to `"approved"` only once the caller has durably persisted the
+ * grant and its authorization code (see `pdpp-auth.ts`'s approve route). A
+ * session marked approved before that write lands would leave a caller whose
+ * persistence failed with no way to retry: the session is already terminal
+ * (`status !== "pending"` above), so a retry of the same reviewed approval
+ * would be rejected as already-decided even though nothing durable exists.
+ */
+export declare function approveAuthorization(input: {
+    sessions: AuthorizationSessionStore;
+    tokens: PdppTokenService;
+    sessionId: string;
+    ownerToken: string | undefined;
+    reviewDigest: string;
+    inventory: InstanceInventory;
+    /**
+     * The owner's instance picks, which must match the ones the review was
+     * rendered with. They feed resolution, so they land inside the recomputed
+     * digest — a different pick than the owner reviewed fails as stale rather
+     * than silently issuing a grant over another instance.
+     */
+    instanceChoices?: Record<string, string[]>;
+    /**
+     * The owner's v0.2 narrowing, which must match the narrowing the review was
+     * rendered with. Like `instanceChoices`, it feeds resolution and so lands
+     * inside the recomputed digest: a narrowing other than the reviewed one
+     * fails as stale rather than silently issuing a different grant.
+     */
+    ownerChoices?: OwnerChoices;
+    /**
+     * The owner's v0.2 conditions and the standing terms that may cover them.
+     * These feed commitment resolution, whose output is a digest field, so a
+     * commitment other than the reviewed one fails as stale.
+     */
+    ownerConditions?: OwnerConditions;
+    standingTerms?: RecipientTerms;
+    explicitAiTrainingConsent?: boolean;
+    now?: Date;
+}): ApprovalResult;
+/**
+ * Deny an authorization. Terminal, and retains no consent evidence — there is
+ * nothing the owner consented to, so there is nothing to hold evidence of.
+ */
+export declare function denyAuthorization(input: {
+    sessions: AuthorizationSessionStore;
+    tokens: PdppTokenService;
+    sessionId: string;
+    ownerToken: string | undefined;
+    /**
+     * The owner's optional free-text reason for refusing.
+     *
+     * Retained with the denial, and deliberately NOT forwarded to the client:
+     * the OAuth binding answers a denial with `access_denied` and nothing more,
+     * so a reason that reached the requester would turn an optional courtesy
+     * into a disclosure the owner did not intend. It exists so the owner's own
+     * record of the decision says why.
+     *
+     * A consent surface must not offer a box whose contents are discarded. The
+     * parameter exists so the control on the screen is real.
+     */
+    reason?: string;
+    now?: Date;
+}): {
+    ok: true;
+} | {
+    ok: false;
+    failure: ApprovalFailure;
+};
+//# sourceMappingURL=approval.d.ts.map

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

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