domainkit 0.12.1 → 0.13.0

package/dist/package.mjs

@@ -1,5 +1,5 @@
 //#region package.json
-var version = "0.12.1";
+var version = "0.13.0";
 //#endregion
 export { version };
 

package/dist/types/Cloudflare.d.ts

@@ -21,37 +21,48 @@ export declare const TokenFields: Schema.Struct<{
 export type AccountContext = typeof AccountContext.Type;
 export interface Options {
     /** Omit to offer tokens only. */
-    readonly oauth?: {
-        readonly clientId: string | Config.Config<string>;
-        readonly clientSecret: Redacted.Redacted<string> | Config.Config<Redacted.Redacted<string>>;
-        /** Scope ids assigned to the OAuth client. Default: `zone:read`, `dns_records:edit`, `offline_access`. */
-        readonly scopes?: ReadonlyArray<string>;
-        /** Default `client_secret_basic`. */
-        readonly clientAuth?: OAuth.ClientAuth;
-        /**
-         * Origin for consent, token exchange, and revocation, which Cloudflare serves at
-         * `/oauth2/auth`, `/oauth2/token`, and `/oauth2/revoke` beneath it. Default
-         * `https://dash.cloudflare.com`; a stage points it at an emulator that mounts the same three
-         * paths. It stays separate from `baseUrl` because in production these are different hosts:
-         * `dash.cloudflare.com` for OAuth, `api.cloudflare.com/client/v4` for the REST API.
-         */
-        readonly issuer?: string;
-        /**
-         * Where the server reaches the OAuth endpoints when that differs from where the browser does,
-         * for example an API in a container reaching an emulator through `host.docker.internal`.
-         * Defaults to `issuer`.
-         */
-        readonly serverOrigin?: string;
-        /**
-         * Permit `http:` for these endpoints when they are not loopback, such as an emulator reached
-         * through `host.docker.internal`. Development only: the client secret, the code, and the tokens
-         * cross the network in the clear, and a name resolves wherever the machine has been told to.
-         * Loopback needs no flag.
-         */
-        readonly allowPlaintext?: boolean;
-    };
+    readonly oauth?: OAuthOptions;
     readonly fetch?: Fetch;
     readonly baseUrl?: string;
 }
+interface OAuthOptionsBase {
+    readonly clientId: string | Config.Config<string>;
+    /** Scope ids assigned to the OAuth client. Default: `zone.read`, `dns.read`, `dns.write`, `offline_access`. */
+    readonly scopes?: ReadonlyArray<string>;
+    /**
+     * Origin for consent, token exchange, and revocation, which Cloudflare serves at
+     * `/oauth2/auth`, `/oauth2/token`, and `/oauth2/revoke` beneath it. Default
+     * `https://dash.cloudflare.com`; a stage points it at an emulator that mounts the same three
+     * paths. It stays separate from `baseUrl` because in production these are different hosts:
+     * `dash.cloudflare.com` for OAuth, `api.cloudflare.com/client/v4` for the REST API.
+     */
+    readonly issuer?: string;
+    /**
+     * Where the server reaches the OAuth endpoints when that differs from where the browser does,
+     * for example an API in a container reaching an emulator through `host.docker.internal`.
+     * Defaults to `issuer`.
+     */
+    readonly serverOrigin?: string;
+    /**
+     * Permit `http:` for these endpoints when they are not loopback, such as an emulator reached
+     * through `host.docker.internal`. Development only: the client secret, the code, and the tokens
+     * cross the network in the clear, and a name resolves wherever the machine has been told to.
+     * Loopback needs no flag.
+     */
+    readonly allowPlaintext?: boolean;
+}
+/** A public OAuth client uses PKCE and has no client secret. */
+export interface PublicOAuthOptions extends OAuthOptionsBase {
+    readonly clientAuth: "none";
+    readonly clientSecret?: never;
+}
+/** A confidential OAuth client authenticates with a required client secret. */
+export interface ConfidentialOAuthOptions extends OAuthOptionsBase {
+    /** Defaults to `client_secret_basic`. */
+    readonly clientAuth?: "client_secret_basic" | "client_secret_post";
+    readonly clientSecret: Redacted.Redacted<string> | Config.Config<Redacted.Redacted<string>>;
+}
+export type OAuthOptions = PublicOAuthOptions | ConfidentialOAuthOptions;
 export declare const server: OAuth.Server;
 export declare const provider: (options?: Options) => Provider.Definition<AccountContext>;
+export {};

package/dist/types/Server.d.ts

@@ -30,9 +30,27 @@ import * as Reason from "./Reason.ts";
 import * as Receipt from "./Receipt.ts";
 import * as Storage from "./Storage.ts";
 import * as Verify from "./Verify.ts";
+/**
+ * What DomainKit already knows about the request when it asks the host who is making it. Only
+ * `/callback/:provider` passes one, because it is the only route that points at a flow DomainKit
+ * recorded earlier; every other route calls `principal` with the request alone.
+ */
+export interface IdentityContext {
+    /** The route being served. */
+    readonly endpoint: EndpointName;
+    /** The flow this callback claims to finish, as DomainKit recorded it when the flow started. */
+    readonly continuation: Storage.ContinuationHeader;
+}
 /** The only service a host must implement for the server. */
 export interface IdentityService {
-    readonly principal: (request: HttpServerRequest.HttpServerRequest) => Effect.Effect<Principal.Interface, Errors.DomainKitError>;
+    /**
+     * `context` is present only on the callback, where a host that keeps per-request tenancy can use
+     * `context.continuation.ownerId` to pick the right tenant out of a session that holds several.
+     * Ignoring it is safe everywhere: DomainKit checks the principal against the recorded flow on
+     * that route regardless, so a host that answers with the wrong one is refused rather than
+     * trusted.
+     */
+    readonly principal: (request: HttpServerRequest.HttpServerRequest, context?: IdentityContext) => Effect.Effect<Principal.Interface, Errors.DomainKitError>;
     /**
      * Which routes this principal may reach, checked after `principal` on every request. Fail with
      * reason `Forbidden` for the 403 a UI expects. Without it every authenticated principal reaches

package/dist/types/Storage.d.ts

@@ -80,6 +80,18 @@ declare const Continuation_base: Schema.Class<Continuation, Schema.Struct<{
 /** Interactive-flow state between `Connect.start` and `Connect.complete`. */
 export declare class Continuation extends Continuation_base {
 }
+declare const ContinuationHeader_base: Schema.Class<ContinuationHeader, Schema.Struct<{
+    readonly ownerId: Schema.String;
+    readonly actorId: Schema.String;
+    readonly provider: Schema.String;
+    readonly expiresAt: Schema.DateTimeUtcFromString;
+}>, {}>;
+/**
+ * Who a continuation belongs to, without the continuation itself. `payload` has no place here: it
+ * carries the PKCE `codeVerifier`, which only the owner-scoped read may reach.
+ */
+export declare class ContinuationHeader extends ContinuationHeader_base {
+}
 export declare const AttemptStatus: Schema.Literals<readonly ["planned", "approved", "applying", "complete", "partial", "failed", "expired", "rejected"]>;
 export type AttemptStatus = typeof AttemptStatus.Type;
 /** Who declined the plan, why, and when. Terminal: the domain needs a new plan. */
@@ -192,6 +204,16 @@ export interface Interface {
         readonly put: (continuation: Continuation) => Fx<void>;
         /** Read without spending; a late read fails `Expired`. */
         readonly get: (id: string) => Fx<Continuation>;
+        /**
+         * The flow's owner, actor, provider, and expiry, without a principal and without spending the
+         * row. The one read in this interface that is not tenant-scoped, because `domainkit/server`
+         * has to learn whose flow a provider callback finishes before it can resolve the principal to
+         * scope by; the callback carries a continuation id and a session cookie and nothing else.
+         *
+         * A missing row fails `NotFound` and a stale one fails `Expired`, exactly as `get` does, so an
+         * expired id never reaches a host. `payload` is out of reach here by construction.
+         */
+        readonly header: (id: string) => Effect.Effect<ContinuationHeader, Errors.DomainKitError>;
         /** Exactly-once: the second consume of the same id fails `NotFound`; a late one fails `Expired`. */
         readonly consume: (id: string) => Fx<Continuation>;
     };
@@ -287,6 +309,8 @@ export interface AsyncInterface {
     readonly continuations: {
         readonly put: (principal: Principal.Interface, continuation: Continuation) => Promise<void>;
         readonly get: (principal: Principal.Interface, id: string) => Promise<Continuation>;
+        /** Takes no principal: see `Interface.continuations.header`. Never returns `payload`. */
+        readonly header: (id: string) => Promise<ContinuationHeader>;
         readonly consume: (principal: Principal.Interface, id: string) => Promise<Continuation>;
     };
     readonly attempts: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "domainkit",
-  "version": "0.12.1",
+  "version": "0.13.0",
   "description": "Build reviewable DNS plans for custom domains in TypeScript",
   "keywords": [
     "custom-domains",