@volter/world-platform 2.0.0

package/dist/src/platform.d.ts

@@ -0,0 +1,77 @@
+import { type SigningKey } from '@volter/world-access';
+import { type Mailer } from './mail.js';
+import { type Backups } from './backup.js';
+import type { BillerFactory } from './biller.js';
+import { type IdentityOptions, type ProviderOptions } from './identity.js';
+import { Store } from './store.js';
+/** An enrolled host: where worlds are provisioned. A world-host, or the hosted World on Cloudflare
+ *  (`apps/cloud`), which answers the same admin doors with the same inventory row. */
+export type HostProvider = {
+    id: string;
+    base: string;
+    adminToken: string;
+};
+/** The platform's enrolled providers: the hosts it provisions onto. */
+export type Providers = {
+    hosts: HostProvider[];
+};
+export type PlatformOptions = {
+    store: Store;
+    /** The header the deploy's own proxy sets to the client's address (`cf-connecting-ip` on Cloudflare, `x-forwarded-for`
+     *  behind a proxy that appends to it): the rate limit keys an unauthenticated request on it. Unset, no request names
+     *  its own address, and unauthenticated requests share one bucket. */
+    clientIpHeader?: string;
+    /** The state directory: the operator token (`<state>/admin`) and the providers record live here. */
+    stateDir?: string;
+    /** Called when the enrolled hosts change (enroll/unenroll) so the record persists. */
+    onProviders?: (providers: Providers) => void;
+    /** The access provider people sign in with (identity.ts): Volter Identity (its `VOLTER_*` names from the env by
+     *  default) or any OpenID Connect issuer, whose directory the platform then keeps in its state. */
+    provider?: ProviderOptions;
+    /** The Volter provider's settings, for callers that name only those. */
+    identity?: IdentityOptions;
+    /** The enrolled hosts; the first is the default target for provisioning. At least one. */
+    hosts: HostProvider[];
+    /** This platform's own public origin, for the OAuth redirect URI. */
+    origin: string;
+    /** A biller to attach (biller.ts; Volter's is apps/billing's `createBiller`). Absent, nothing is limited or priced. */
+    billing?: BillerFactory;
+    /** The platform's own mail: a member added or invited, a World deleted, and the biller's notices (mail.ts; the resend twin in rehearsal). */
+    mail?: Mailer;
+    /** The product's site (the front door): its docs, and the terms and privacy a person accepts at org creation.
+     *  Absent (a self-hosted platform), no terms are asked for. */
+    siteUrl?: string;
+    /** Where the Help form's mail goes (layer 6, a flag: --support-to); absent, the request is kept and logged only. */
+    supportTo?: string;
+    /** Backups of the state directory to S3 through the boundary (backup.ts); absent when no --backup-bucket is named. */
+    backups?: Backups;
+    /** Requests a person or an org may make per minute against the doors (plans.ts may raise it later). */
+    rateLimitPerMinute?: number;
+    /** The platform's own clock (layer 5): the tick's cadence in seconds (0 = never; default 3600) and the backup's time of day, UTC HH:MM (default 00:00). */
+    clock?: {
+        tickEverySeconds?: number;
+        backupAt?: string;
+        deliverEverySeconds?: number; /** how often the keys of people no longer in an org are swept from its Worlds (seconds; 0 = never; default 3600) */
+        sweepMembersEverySeconds?: number;
+    };
+    /** The key the platform signs passes with (docs/contributing/architecture.md, "The hosted product"); its public half
+     *  is published at /.well-known/jwks.json for the hosts that trust this platform. Absent, no World opens by pass. */
+    signingKey?: SigningKey;
+};
+export declare function createPlatform(opts: PlatformOptions): {
+    fetch: (request: Request) => Promise<Response>;
+    stop: () => void;
+};
+/** Serve a platform on a port, under Node or Bun (world-core's serve seam). `origin` is where people reach it (behind a
+ *  proxy, its public address); by default the address it listens on. */
+export declare function servePlatform(opts: Omit<PlatformOptions, 'origin'> & {
+    port?: number;
+    host?: string;
+    origin?: string;
+}): Promise<{
+    url: string;
+    port: number;
+    stop: () => Promise<void>;
+}>;
+/** The platform's operator token: minted once, kept at `<state>/admin` (0600) — the host's pattern, never an env. */
+export declare function operatorTokenFor(stateDir: string): string;