@opendatalabs/personal-server-ts-server 1.33.8 → 1.34.0

package/dist/routes/pdpp-auth.d.ts

@@ -0,0 +1,157 @@
+/**
+ * PDPP Core v0.1.0 Authorization Server HTTP surface.
+ *
+ * The endpoints under `/pdpp/v1`:
+ *
+ *   POST /authorize                      — accept an RFC 9396 selection request
+ *   GET  /authorize/:session_id/review   — the owner's consent review model
+ *   POST /authorize/:session_id/approve  — authenticated owner approval
+ *   POST /authorize/:session_id/deny     — authenticated owner denial
+ *   POST /token                          — code redemption + refresh rotation
+ *   POST /introspect                     — RFC 7662 introspection
+ *   GET  /grants                         — the owner's grants, with status
+ *   POST /revoke                         — owner-initiated grant revocation
+ *
+ * This is deliberately a NEW surface rather than an extension of
+ * `oauth-token.ts`. That endpoint serves the control-plane and CLI device
+ * flows against the legacy `TokenStore`; PDPP tokens are grant-bound and live
+ * in their own store with their own lifecycle. Mixing them would mean one
+ * endpoint with two token authorities, which §8 explicitly warns against
+ * ("do not query or create a second grant authority"). Existing clients of
+ * `/oauth/token` are untouched.
+ *
+ * Every response carries `Cache-Control: no-store` and `Pragma: no-cache`
+ * (RFC 6749 §5.1 for token responses; delivery scope §1 requires it on every
+ * token response specifically).
+ *
+ * Two things that cost integrators a debug cycle, so stated plainly:
+ *
+ *   - **Content types differ by endpoint.** `/authorize`, `/approve` and
+ *     `/deny` take JSON. `/token`, `/introspect` and `/revoke` take
+ *     `application/x-www-form-urlencoded`, because they follow the RFC 6749 /
+ *     7662 / 7009 wire conventions a standard OAuth client library already
+ *     speaks. Sending JSON to the form endpoints parses to an empty body and
+ *     reads as a missing parameter.
+ *   - **The review digest is nested.** `GET /authorize/:id/review` returns
+ *     `{ session_id, review, expires_at }`, so the digest is at
+ *     `review.review_digest`, not at the top level. The envelope also carries
+ *     `instance_choice_required` instead of `review` when the owner still has
+ *     an instance to pick.
+ */
+import { Hono, type Context } from "hono";
+import type { Logger } from "pino";
+import type { ClientIdentityResult } from "@opendatalabs/personal-server-ts-core/pdpp";
+import type { AuthorizationSessionStore, PdppTokenService } from "@opendatalabs/personal-server-ts-core/pdpp";
+import { type DeclarationSnapshot, type InstanceInventory, type PdppAuthStore, type RecipientTerms, type RegisteredRedirectPolicy, type SelectionRequest } from "@opendatalabs/personal-server-ts-core/pdpp";
+import type { TokenStore } from "../token-store.js";
+/** Owner tokens are short-lived: they authorize consent decisions. */
+export declare const OWNER_TOKEN_TTL_SECONDS: number;
+export interface PdppAuthRouteDeps {
+    logger: Logger;
+    store: PdppAuthStore;
+    tokens: PdppTokenService;
+    sessions: AuthorizationSessionStore;
+    /**
+     * Resolve the retained declaration snapshot for a source. The AS resolves
+     * only against this snapshot — never a live re-fetch at approval time.
+     */
+    resolveDeclaration(sourceId: string): DeclarationSnapshot | null;
+    /** Resolve an owner-token source from the independent connection registry. */
+    resolveConnectionSourceId?(sourceId: string): string | undefined;
+    /** The owner's connected instances, read fresh at review and approval. */
+    inventoryFor(subjectId: string, sourceId: string): InstanceInventory;
+    connectionState?(instanceId: string): {
+        sourceId: string | null;
+        deleted: boolean;
+    };
+    /**
+     * The authenticated owner for an incoming authorization request. Returns
+     * null when no owner session is present.
+     */
+    currentSubjectId(c: Context): string | null;
+    /**
+     * Resolve the PDPP subject for a request that already passed the PS owner
+     * proof (`web3-auth` + `owner-check`). Used only by
+     * `POST /owner/token`. Defaults to `currentSubjectId` when a deployment
+     * uses one notion of owner identity for both.
+     */
+    ownerSubjectId?(c: Context): string | null;
+    /**
+     * Owner-proof wiring. When supplied, `POST /owner/token` is guarded by the
+     * PS's existing `web3-auth` + `owner-check` middleware — the same wallet
+     * signature chain every other owner route uses — and the verified signer
+     * becomes the PDPP subject. Absent, the route falls back to
+     * `ownerSubjectId`/`currentSubjectId`, which is how the unit tests drive it.
+     */
+    ownerAuth?: {
+        serverOrigin: string | (() => string);
+        serverOwner?: `0x${string}`;
+        devToken?: string;
+        accessToken?: string;
+        tokenStore?: TokenStore;
+    };
+    /**
+     * Registered metadata for a client, used to validate `redirect_uri` by
+     * exact match (RFC 6749 §3.1.2.2). Returning null means the client is
+     * unregistered, and an unregistered client cannot receive an authorization
+     * code — the AS fails closed rather than trusting the requested target.
+     */
+    registeredClient?(clientId: string): RegisteredRedirectPolicy | null;
+    /**
+     * Resolve a URL-hosted client identity (§6) when a client is not locally
+     * registered. Optional: leaving it unset preserves registration-only
+     * behavior exactly, and performs no outbound fetch.
+     */
+    resolveClientIdentity?(clientId: string): Promise<ClientIdentityResult>;
+    /**
+     * AS-policy grant expiry, when the deployment sets one.
+     *
+     * `clientId` is the second argument (not folded into `request`) because it
+     * is authorization-request context, not part of the RFC 9396 selection
+     * request itself — Core's `SelectionRequest` stays binding-neutral and
+     * carries no client identity. `request` remains first for compatibility
+     * with any existing caller that only closed over it.
+     */
+    grantExpiryFor?(request: SelectionRequest, clientId: string): string | undefined;
+    /**
+     * Require PKCE on the authorization code flow. Defaults to true and should
+     * stay true: PDPP clients are public clients, so without a verifier an
+     * intercepted code is redeemable by whoever intercepted it.
+     */
+    requirePkce?: boolean;
+    /**
+     * Standing terms this client has authorized, when the deployment tracks
+     * them.
+     *
+     * Absent means the AS knows of no standing terms, which is the safe default
+     * rather than a gap: with no terms, only conditions the client's own request
+     * already covers can become commitments, and anything else refuses. v0.2 is
+     * explicit that a capability advertisement is not acceptance, so an AS that
+     * cannot evidence acceptance must not assume it.
+     */
+    standingTermsFor?(clientId: string): RecipientTerms | null;
+    /**
+     * This authorization server's issuer identifier, used to build the absolute
+     * endpoint URLs in its metadata document. Absent omits the document
+     * entirely rather than publishing relative or guessed URLs — a client that
+     * cannot resolve the endpoints is worse off than one that finds no document
+     * and falls back to configuration.
+     */
+    issuer?: string | (() => string);
+}
+/**
+ * The PDPP AS metadata document, as a handler both of its locations share.
+ *
+ * Exported because the two URLs it is served at live in different routers: the
+ * path-first one inside `/pdpp/v1`, and the RFC 8414 §3 one
+ * (`/.well-known/oauth-authorization-server/pdpp/v1`) at the app root, outside
+ * this prefix. One handler rather than two so the documents can never drift --
+ * a client discovering through either must find the same authority.
+ *
+ * `issuer` is accepted as a thunk for deployments that resolve their own origin
+ * late (a bound port unknown at construction). It is resolved per request so
+ * the document never advertises a stale origin.
+ */
+export declare function pdppAsMetadataHandler(issuerSource: PdppAuthRouteDeps["issuer"]): (c: Context) => Response;
+export declare function pdppAuthRoutes(deps: PdppAuthRouteDeps): Hono;
+//# sourceMappingURL=pdpp-auth.d.ts.map

package/dist/routes/pdpp-auth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pdpp-auth.d.ts","sourceRoot":"","sources":["../../src/routes/pdpp-auth.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AAEH,OAAO,EAAE,IAAI,EAAE,KAAK,OAAO,EAAE,MAAM,MAAM,CAAC;AAC1C,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,MAAM,CAAC;AACnC,OAAO,KAAK,EACV,oBAAoB,EAErB,MAAM,4CAA4C,CAAC;AACpD,OAAO,KAAK,EACV,yBAAyB,EACzB,gBAAgB,EACjB,MAAM,4CAA4C,CAAC;AACpD,OAAO,EAYL,KAAK,mBAAmB,EAExB,KAAK,iBAAiB,EAGtB,KAAK,aAAa,EAClB,KAAK,cAAc,EACnB,KAAK,wBAAwB,EAC7B,KAAK,gBAAgB,EAEtB,MAAM,4CAA4C,CAAC;AAIpD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AASpD,sEAAsE;AACtE,eAAO,MAAM,uBAAuB,QAAU,CAAC;AAE/C,MAAM,WAAW,iBAAiB;IAChC,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,aAAa,CAAC;IACrB,MAAM,EAAE,gBAAgB,CAAC;IACzB,QAAQ,EAAE,yBAAyB,CAAC;IACpC;;;OAGG;IACH,kBAAkB,CAAC,QAAQ,EAAE,MAAM,GAAG,mBAAmB,GAAG,IAAI,CAAC;IACjE,8EAA8E;IAC9E,yBAAyB,CAAC,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC;IACjE,0EAA0E;IAC1E,YAAY,CAAC,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,iBAAiB,CAAC;IACrE,eAAe,CAAC,CAAC,UAAU,EAAE,MAAM,GAAG;QACpC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;QACxB,OAAO,EAAE,OAAO,CAAC;KAClB,CAAC;IACF;;;OAGG;IACH,gBAAgB,CAAC,CAAC,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAAC;IAC5C;;;;;OAKG;IACH,cAAc,CAAC,CAAC,CAAC,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAAC;IAC3C;;;;;;OAMG;IACH,SAAS,CAAC,EAAE;QACV,YAAY,EAAE,MAAM,GAAG,CAAC,MAAM,MAAM,CAAC,CAAC;QACtC,WAAW,CAAC,EAAE,KAAK,MAAM,EAAE,CAAC;QAC5B,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,UAAU,CAAC,EAAE,UAAU,CAAC;KACzB,CAAC;IACF;;;;;OAKG;IACH,gBAAgB,CAAC,CAAC,QAAQ,EAAE,MAAM,GAAG,wBAAwB,GAAG,IAAI,CAAC;IACrE;;;;OAIG;IACH,qBAAqB,CAAC,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,oBAAoB,CAAC,CAAC;IACxE;;;;;;;;OAQG;IACH,cAAc,CAAC,CACb,OAAO,EAAE,gBAAgB,EACzB,QAAQ,EAAE,MAAM,GACf,MAAM,GAAG,SAAS,CAAC;IACtB;;;;OAIG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB;;;;;;;;;OASG;IACH,gBAAgB,CAAC,CAAC,QAAQ,EAAE,MAAM,GAAG,cAAc,GAAG,IAAI,CAAC;IAC3D;;;;;;OAMG;IACH,MAAM,CAAC,EAAE,MAAM,GAAG,CAAC,MAAM,MAAM,CAAC,CAAC;CAClC;AA8HD;;;;;;;;;;;;GAYG;AACH,wBAAgB,qBAAqB,CACnC,YAAY,EAAE,iBAAiB,CAAC,QAAQ,CAAC,GACxC,CAAC,CAAC,EAAE,OAAO,KAAK,QAAQ,CAoC1B;AAED,wBAAgB,cAAc,CAAC,IAAI,EAAE,iBAAiB,GAAG,IAAI,CAy6B5D"}