@decentnetwork/beagle-service 0.0.0-stage → 0.2.0

package/dist/types.d.ts

@@ -0,0 +1,641 @@
+import type { NetworkNode, Peer, PeerOptions } from "@decentnetwork/peer";
+export type UserStatus = "visitor" | "registered" | "blocked";
+/** One record per userid. A site may add fields of its own; every update
+ *  merges into the stored record, so fields this library does not know stay. */
+export interface UserRecord {
+    /** The identity: base58 of the X25519 public key that signed. */
+    userid: string;
+    /** Full Carrier address (key + nospam + checksum), needed to send a friend
+     *  request. Not signed at sign-in: checked to parse and to name `userid`. */
+    address: string | null;
+    /** Display hints from the visitor's Beagle. Not signed. */
+    name: string | null;
+    avatar: string | null;
+    punkId: number | null;
+    /** Which Beagle answered: the popup's origin, or "launch" for an Apps-tab arrival. */
+    door: string | null;
+    /** The origin of the site's page the last sign-in was signed for. */
+    origin?: string | null;
+    status: UserStatus;
+    /** The site's registration fields (`register.required` / `register.optional`). */
+    profile: Record<string, unknown>;
+    /** ISO 8601. null for a userid that was blocked before it ever signed in. */
+    firstSeen: string | null;
+    lastSeen: string | null;
+    /** Bursts of activity, separated by `visitor.visitGapMinutes` of silence. */
+    visits: number;
+    /** Successful sign-ins and Apps-tab launches. */
+    signIns: number;
+    registeredAt?: string | null;
+    blocked?: {
+        at: string;
+        why: string;
+        was: "visitor" | "registered";
+    } | null;
+    /** ms since the epoch; a session issued before this moment is refused. */
+    sessionsValidFrom?: number;
+    /** What the userid published under a beagles.eth name (`importProfile`). */
+    published?: PublishedProfile | null;
+    [key: string]: unknown;
+}
+export interface PublishedProfile {
+    name?: string;
+    displayName?: string;
+    description?: string;
+    avatar?: string;
+    url?: string;
+    /** The record's owner. When it equals the userid, that key published it. */
+    owner?: string;
+    fetchedAt: string;
+}
+/** What one write changed, as the second argument of `UserStore.put`. */
+export interface UserChange {
+    /** The record as it was read for this write; null when there was none. */
+    prev: UserRecord | null;
+    /** Top-level fields that were added or got a new value, with that value. */
+    set: Record<string, unknown>;
+    /** Top-level fields that were removed. */
+    unset: string[];
+}
+/** Where users are kept. Implement these three calls for Postgres, sqlite or
+ *  anything else.
+ *
+ *  `get` may return any object that names the userid; fields this library
+ *  needs and does not find are filled in when it is read (a record that
+ *  predates the library is fine).
+ *
+ *  `put` receives the whole record, including fields the store does not
+ *  recognise, and as a second argument what this write changed. A store that
+ *  other code writes to as well should store only `change.set` and remove
+ *  `change.unset`: then a field somebody else wrote since the read is not
+ *  written back from an old copy. A store that ignores the second argument
+ *  and stores the whole record (an adapter written for 0.1.0) keeps working.
+ *
+ *  When `get` and `put` are synchronous, the library calls them in the same
+ *  turn of the event loop with nothing in between. */
+export interface UserStore {
+    get(userid: string): Promise<UserRecord | null> | UserRecord | null;
+    put(user: UserRecord, change?: UserChange): Promise<void> | void;
+    list(): Promise<UserRecord[]> | UserRecord[];
+}
+/** Small durable sets with expiry: used nonces, used launch assertions and
+ *  revoked sessions. With several server processes, back this with a shared
+ *  database; `addOnce` must then be atomic there (an insert that fails on a
+ *  duplicate key). */
+export interface StateStore {
+    /** Remember `key` in `ns` until `expiresAt` (ms). true when it was not
+     *  there, or had expired; false when it was. */
+    addOnce(ns: string, key: string, expiresAt: number): Promise<boolean> | boolean;
+    has(ns: string, key: string): Promise<boolean> | boolean;
+}
+export interface RegisterConfig {
+    /** Fields a visitor must give to become a registered user. Empty (the
+     *  default): every visitor is a registered user at once. */
+    required?: string[];
+    /** Fields the register route also accepts and stores. */
+    optional?: string[];
+    /** Confirm one submitted field. Return true to accept, false or a string
+     *  (the reason, shown to the page) to refuse, or `{ value }` to store a
+     *  normalised value. `submitted` is everything the page posted, so a site
+     *  can read a confirmation code it asked for. Sending the email or the SMS
+     *  is the site's part. */
+    verify?: (field: string, value: unknown, user: UserRecord, submitted: Record<string, unknown>) => boolean | string | {
+        value: unknown;
+    } | Promise<boolean | string | {
+        value: unknown;
+    }>;
+}
+export interface VisitorConfig {
+    /** Days after `firstSeen` a visitor may stay unregistered. */
+    maxDays?: number;
+    /** Visits a visitor may make unregistered. */
+    maxVisits?: number;
+    /** After the limit: "ask" keeps answering and marks registration as due;
+     *  "refuse" answers 403 `register-required` until they register. Default "ask". */
+    then?: "ask" | "refuse";
+    /** Silence that separates two visits. Default 30. */
+    visitGapMinutes?: number;
+}
+/** What the page is told about registration. */
+export interface RegistrationState {
+    status: UserStatus;
+    required: string[];
+    optional: string[];
+    /** Required fields the user has not given yet. */
+    missing: string[];
+    /** The visitor limit has passed and fields are missing. */
+    due: boolean;
+    /** `due`, and the site answers 403 until they register. */
+    refused: boolean;
+    /** When `visitor.maxDays` runs out (ISO 8601), if it is set. */
+    deadline?: string;
+    /** Visits left before `visitor.maxVisits` is reached, if it is set. */
+    visitsLeft?: number;
+}
+export type RegisterResult = {
+    ok: true;
+    user: UserRecord;
+} | {
+    ok: false;
+    error: "invalid-fields";
+    fields: Record<string, string>;
+} | {
+    ok: false;
+    error: "blocked" | "not-found";
+};
+export interface UsersEvents {
+    /** After every successful sign-in or launch. */
+    "sign-in": [user: UserRecord, info: {
+        first: boolean;
+        door: string | null;
+        origin: string | null;
+    }];
+    /** A visitor became a registered user. */
+    registered: [user: UserRecord];
+    blocked: [user: UserRecord];
+    unblocked: [user: UserRecord];
+    [event: string]: unknown[];
+}
+export interface Users {
+    get(userid: string): Promise<UserRecord | null>;
+    /** All users, or those with one status. */
+    list(filter?: {
+        status?: UserStatus;
+    }): Promise<UserRecord[]>;
+    /** Merge `patch` into the record (one level deep for `profile`). Fields
+     *  the patch does not name are kept, known to this library or not. */
+    update(userid: string, patch: Partial<UserRecord>): Promise<UserRecord>;
+    /** Refuse this userid: sign-in answers 403 `blocked`, its sessions stop
+     *  working, and the agent refuses and removes it as a friend. Works for a
+     *  userid that has never signed in. */
+    block(userid: string, why?: string): Promise<UserRecord>;
+    unblock(userid: string): Promise<UserRecord | null>;
+    /** End every session of this user (they sign in again). */
+    revokeSessions(userid: string): Promise<void>;
+    /** Check and store registration fields; a visitor with every required
+     *  field becomes `registered`. */
+    register(userid: string, submitted: Record<string, unknown>): Promise<RegisterResult>;
+    registration(user: UserRecord): RegistrationState;
+    /** Record a sign-in the site verified by a door of its own. The two built-in
+     *  doors call this themselves. */
+    recordSignIn(userid: string, hints?: {
+        address?: unknown;
+        name?: unknown;
+        avatar?: unknown;
+        punkId?: unknown;
+    }, info?: {
+        door?: string | null;
+        origin?: string | null;
+    }): Promise<UserRecord>;
+    /** Note activity: `lastSeen`, and `visits` after a gap. Written at most
+     *  once a minute per user. */
+    touch(userid: string): Promise<UserRecord | null>;
+    /** Read the userid's beagles.eth record and store it under `published`. */
+    importProfile(userid: string): Promise<PublishedProfile | null>;
+    on<K extends keyof UsersEvents>(event: K, cb: (...args: UsersEvents[K]) => unknown): () => void;
+}
+export interface SessionConfig {
+    /** Days until a session expires. Default 30. */
+    ttlDays?: number;
+    /** "cookie" (default): HttpOnly cookie. "bearer": the token is returned in
+     *  the sign-in answer and sent back as `Authorization: Bearer`. "both". */
+    transport?: "cookie" | "bearer" | "both";
+    /** Default "beagle_session". */
+    cookieName?: string;
+    /** Default "Lax". */
+    sameSite?: "Lax" | "Strict" | "None";
+    cookieDomain?: string;
+    /** Default "/". */
+    cookiePath?: string;
+    /** `authenticate()` notes the user's activity (`lastSeen`, `visits`), which
+     *  is one write to the users store per user per minute at most. false: it
+     *  only reads. One call can say otherwise with `authenticate(req, { touch })`.
+     *  Default true. */
+    touch?: boolean;
+}
+/** A limit on sign-in and launch attempts, counted in memory per process. */
+export interface RateLimitConfig {
+    /** Attempts one client may make per window. Default 30. */
+    perClient?: number;
+    /** Attempts all clients together may make per window. Default 600. */
+    total?: number;
+    /** Default 60. */
+    windowSeconds?: number;
+    /** Read the client's address from `X-Forwarded-For`: true for one proxy in
+     *  front of the server, or how many. Default false: the connection's own
+     *  address, and a connection from this machine (a local proxy) counts
+     *  against `total` only. */
+    trustProxy?: boolean | number;
+    /** Name the client yourself; null counts against `total` only. */
+    key?: (request: ServiceRequest) => string | null | undefined;
+}
+/** What `onSignIn` is told beside the user. */
+export interface SignInInfo {
+    /** The origin of the site's page the assertion was signed for. */
+    origin: string;
+    /** Which Beagle answered: the popup's origin, or "launch". */
+    door: string | null;
+    /** Which route verified it. */
+    route: "sign-in" | "launch";
+    /** The first sign-in of this userid. */
+    first: boolean;
+    /** The request as the route got it (`raw` is the framework's own object,
+     *  when an adapter made the request). */
+    request: ServiceRequest;
+}
+/** Refuse a sign-in from `onSignIn`: no session is issued. */
+export interface SignInRefusal {
+    /** true, or the `error` code the page gets. Default "sign-in-refused". */
+    refuse: true | string;
+    /** Default 403. */
+    status?: number;
+    message?: string;
+}
+/** Runs after the assertion is verified and the user record is written, and
+ *  before the session is issued and the answer goes out. Return an object and
+ *  its fields are added to the sign-in answer (the library's own fields win);
+ *  return `{ refuse }` to refuse. It is awaited; if it throws, the sign-in
+ *  answers 500 and no session is issued. */
+export type SignInHook = (user: UserRecord, info: SignInInfo) => void | Record<string, unknown> | SignInRefusal | Promise<void | Record<string, unknown> | SignInRefusal>;
+export interface SessionInfo {
+    userid: string;
+    /** Session id; logout revokes this. */
+    sid: string;
+    issuedAt: number;
+    expiresAt: number;
+    /** How the token arrived. */
+    via: "cookie" | "bearer";
+}
+export type ErrorCode = "origin-not-allowed" | "bad-request" | "bad-nonce" | "bad-signature" | "launch-expired" | "launch-replayed" | "blocked" | "register-required" | "sign-in-refused" | "rate-limited" | "not-signed-in" | "invalid-fields" | "not-found" | "method-not-allowed" | "too-large" | "server-error";
+export type VerifyResult = {
+    ok: true;
+    userid: string;
+    hints: {
+        address?: unknown;
+        name?: unknown;
+        avatar?: unknown;
+        punkId?: unknown;
+    };
+    door: string | null;
+} | {
+    ok: false;
+    status: number;
+    error: ErrorCode;
+};
+export type AuthResult = {
+    ok: true;
+    user: UserRecord;
+    session: SessionInfo;
+    registration: RegistrationState;
+} | {
+    ok: false;
+    status: number;
+    error: ErrorCode;
+    user?: UserRecord;
+    session?: SessionInfo;
+    registration?: RegistrationState;
+};
+/** Anything with request headers: a node `IncomingMessage`, an Express or
+ *  Next.js request, a `ServiceRequest`, or a bare `{ headers }`. */
+export interface HeadersCarrier {
+    headers: Record<string, string | string[] | undefined> | {
+        get(name: string): string | null;
+    };
+    method?: string;
+}
+/** The exact origins of the site's pages: a list, or a function that returns
+ *  the list as it is now (called on each request; keep it cheap). */
+export type OriginsSource = string[] | (() => string[]);
+export interface AuthenticateOptions {
+    /** Let a visitor past the limit through (the register route does). */
+    allowUnregistered?: boolean;
+    /** Note the user's activity; see `session.touch`. */
+    touch?: boolean;
+    /** For the site's own state-changing routes: a session that arrived in a
+     *  cookie is accepted only when the request's `Origin` header is on the
+     *  list (403 `origin-not-allowed` otherwise). A bearer token needs no
+     *  Origin. When the request object has a `method` and it is GET, HEAD or
+     *  OPTIONS, nothing is checked, so the option can be passed on every call. */
+    checkOrigin?: boolean;
+}
+export interface Auth {
+    /** A single-use nonce that lives 120 s. */
+    issueNonce(): string;
+    /** The request's `Origin` header when it is on the exact list, else null. */
+    allowedOrigin(req: HeadersCarrier): string | null;
+    /** The exact origins accepted now. */
+    origins(): string[];
+    /** Replace the list while running. Throws on a malformed entry and keeps
+     *  the list it had. Used nonces, launch assertions and sessions are not
+     *  touched. */
+    setOrigins(origins: OriginsSource): void;
+    /** Check a `decent-auth` assertion: origin, nonce, signature. The nonce is
+     *  spent by the sign-in that verifies; one that fails writes nothing. */
+    verifySignIn(origin: string | null | undefined, body: unknown): Promise<VerifyResult>;
+    /** Check a `decent-launch` assertion: origin, ±120 s, signature, then replay (consumed last, kept on disk). */
+    verifyLaunch(origin: string | null | undefined, body: unknown): Promise<VerifyResult>;
+    /** Who is making this request, for the site's own routes. Refuses a blocked
+     *  user (403 `blocked`) and a visitor past the limit under `then: "refuse"`
+     *  (403 `register-required`) unless `allowUnregistered` is set. Never
+     *  rejects: no session, a bad one, or a store that cannot be read all answer
+     *  `ok: false` (the last with status 500 `server-error`). */
+    authenticate(req: HeadersCarrier, opts?: AuthenticateOptions): Promise<AuthResult>;
+    /** A session token for `userid`. */
+    mintSession(userid: string): {
+        token: string;
+        sid: string;
+        expiresAt: number;
+    };
+    /** The token's content when it is ours, untampered and unexpired. Does not
+     *  look at revocation or the user; `authenticate` does. */
+    readToken(token: string): {
+        userid: string;
+        sid: string;
+        issuedAt: number;
+        expiresAt: number;
+    } | null;
+    /** The session token the request carries (bearer first, then the cookie), or null. */
+    tokenOf(req: HeadersCarrier): string | null;
+    /** Revoke one session token (logout). */
+    revoke(token: string): Promise<void>;
+    /** The `Set-Cookie` value carrying `token`, or clearing it when `token` is null. */
+    cookie(token: string | null, origin?: string | null): string;
+}
+export interface ServiceRequest {
+    method: string;
+    /** Path below the prefix: "/nonce", "/sign-in", "/launch", "/me", "/logout", "/register". */
+    path?: string;
+    headers: Record<string, string | string[] | undefined>;
+    /** The parsed JSON body of a POST. */
+    body?: unknown;
+    /** The client's address, for the rate limit. The adapters fill it in. */
+    ip?: string | null;
+    /** The framework's own request object, when an adapter made this one. */
+    raw?: unknown;
+}
+export interface ServiceResponse {
+    status: number;
+    headers: Record<string, string | string[]>;
+    /** A JSON-serialisable object, or null for an empty answer. */
+    body: Record<string, unknown> | null;
+}
+export type RouteHandler = (req: ServiceRequest) => Promise<ServiceResponse>;
+export interface Handlers {
+    nonce: RouteHandler;
+    signIn: RouteHandler;
+    launch: RouteHandler;
+    me: RouteHandler;
+    logout: RouteHandler;
+    register: RouteHandler;
+}
+export type RouteName = keyof Handlers;
+export interface AdapterOptions {
+    /** Where the routes are mounted. Default "/api/auth". */
+    prefix?: string;
+}
+/** `(req, res, next?)`: a `node:http` listener, an Express middleware and a
+ *  Next.js API route all have this shape. */
+export type NodeHandler = (req: any, res: any, next?: (err?: unknown) => void) => Promise<void>;
+/** A friend request as the policy sees it. */
+export interface FriendRequestInfo {
+    userid: string;
+    address?: string;
+    name?: string;
+    description?: string;
+    hello?: string;
+    punkId?: number;
+    avatarUrl?: string;
+    /** ISO 8601. */
+    arrivedAt: string;
+}
+/** true accepts, false holds the request (it is looked at again when the
+ *  sender signs in, registers or is unblocked), "reject" refuses it. */
+export type FriendPolicyFn = (request: FriendRequestInfo, user: UserRecord | null) => boolean | "reject" | Promise<boolean | "reject">;
+export type FriendPolicy = "all" | "signed-in" | "registered" | "manual" | FriendPolicyFn;
+export interface AgentServers {
+    bootstrapNodes: NetworkNode[];
+    expressNodes?: NetworkNode[];
+}
+export interface AgentConfig {
+    /** The identity's key file; created on first start. Default `<dataDir>/agent/peer.save`. */
+    keyFile?: string;
+    nickname?: string;
+    statusMessage?: string;
+    punkId?: number;
+    avatarUrl?: string;
+    /** Who may become a friend. Default "signed-in": the userid has a user record. */
+    accept?: FriendPolicy;
+    /** Send a friend request from the agent to the user's stored address. Default "never". */
+    befriendOn?: "sign-in" | "register" | "never";
+    /** The greeting in friend requests the agent sends. Default: the nickname. */
+    hello?: string;
+    /** Days an unanswered request is kept. Default 7. */
+    holdDays?: number;
+    /** Bootstrap and Express nodes, or the URL of a list in the Beagle apps'
+     *  `bgservers.json` format. Default `DEFAULT_SERVERS_URL`. */
+    servers?: AgentServers | string;
+    /** Hours a message may wait in the outbox before it is dead-lettered. Default 72. */
+    maxQueueHours?: number;
+    /** Extra options passed to `Peer.create` (for example `udpPort`). */
+    peerOptions?: Partial<PeerOptions>;
+}
+/** The part of `Peer` the agent uses. */
+export type AgentPeer = Pick<Peer, "userid" | "address" | "start" | "stop" | "joinNetwork" | "friends" | "sessionStatus" | "onFriendRequest" | "acceptFriendRequest" | "rejectFriendRequest" | "removeFriend" | "sendFriendRequest" | "onFriendConnection" | "onText" | "sendText" | "sendTextUntilAck" | "sendTextViaExpress">;
+export interface IncomingMessage {
+    /** The sender's key. Act on this, never on a userid written in the text. */
+    userid: string;
+    /** The sender's user record, or null when they never signed in on the site. */
+    user: UserRecord | null;
+    text: string;
+    deliveryId?: string;
+    via?: "online" | "offline";
+    /** Queue an answer to the sender. */
+    reply(text: string): Promise<SendReceipt>;
+}
+export interface SendReceipt {
+    /** Outbox id of the message. */
+    id: string;
+    /** One per part; a long text is split. Stable across retries and restarts. */
+    deliveryIds: string[];
+    state: "queued" | "dead";
+    /** Why it was dead-lettered at once. */
+    why?: DeadLetterReason;
+}
+export type DeadLetterReason = "not-a-friend" | "bad-address" | "blocked" | "expired";
+export interface OutboxItem {
+    id: string;
+    /** Part of the message `id` (0-based) and how many parts it has. */
+    part: number;
+    parts: number;
+    to: string;
+    text: string;
+    deliveryId: string;
+    createdAt: string;
+    attempts: number;
+    /** ms; not tried again before this. */
+    nextAt: number;
+    lastError?: string;
+}
+export interface DeliveryEvent {
+    id: string;
+    deliveryId: string;
+    to: string;
+    /** "online": a live session took it. "offline": posted to an Express node. */
+    via: "online" | "offline";
+    /** The friend's side confirmed receipt (only possible on the live road). */
+    confirmed: boolean;
+}
+export interface DeadLetter {
+    at: string;
+    why: DeadLetterReason;
+    error?: string;
+    item: OutboxItem;
+}
+export type BefriendResult = {
+    ok: true;
+    how: "requested" | "accepted" | "already-friends" | "already-asked";
+} | {
+    ok: false;
+    reason: "blocked" | "no-address" | "unknown-user" | "send-failed";
+    error?: string;
+};
+export interface AgentEvents {
+    /** A request the policy did not accept yet; it is kept on disk. */
+    "request-held": [request: FriendRequestInfo];
+    "friend-accepted": [info: {
+        userid: string;
+    }];
+    "friend-refused": [info: {
+        userid: string;
+        why: "blocked" | "policy" | "manual" | "expired";
+    }];
+    "friend-removed": [info: {
+        userid: string;
+    }];
+    delivered: [event: DeliveryEvent];
+    "dead-letter": [letter: DeadLetter];
+    [event: string]: unknown[];
+}
+export interface Agent {
+    /** The agent's own identity. Print `address` where people can add it. */
+    readonly userid: string;
+    readonly address: string;
+    readonly nickname: string | undefined;
+    /** Resolves when the peer has joined the network. Sign-in routes do not wait for it. */
+    readonly ready: Promise<void>;
+    /** The underlying `@decentnetwork/peer` instance, for what this library leaves out (files, calls, groups). */
+    readonly peer: AgentPeer;
+    /** Queue a text for a friend. Resolves once the message is on disk;
+     *  delivery starts on the next turn of the event loop. */
+    send(userid: string, text: string): Promise<SendReceipt>;
+    onMessage(cb: (message: IncomingMessage) => unknown): () => void;
+    /** Send a friend request to the user's stored address (once; `force` asks again). */
+    befriend(userid: string, opts?: {
+        hello?: string;
+        force?: boolean;
+    }): Promise<BefriendResult>;
+    isFriend(userid: string): boolean;
+    /** Requests waiting on disk. */
+    pending(): FriendRequestInfo[];
+    /** Accept or refuse a held request by hand. */
+    accept(userid: string): Promise<boolean>;
+    reject(userid: string): Promise<boolean>;
+    /** Drop a friend. */
+    unfriend(userid: string): boolean;
+    /** Messages not delivered yet. */
+    outbox(): OutboxItem[];
+    deadLetters(): DeadLetter[];
+    on<K extends keyof AgentEvents>(event: K, cb: (...args: AgentEvents[K]) => unknown): () => void;
+    stop(): Promise<void>;
+}
+export interface BeagleServiceConfig {
+    /** Exact origins the site's pages are served from, e.g. "https://your.app"
+     *  (scheme, host, port). No suffix matching. `http://localhost:3000` only
+     *  when it is listed. A function is called on each request, for a list that
+     *  changes while the server runs; `auth.setOrigins()` does the same from
+     *  outside. A malformed entry throws when the service is created. */
+    origins: OriginsSource;
+    /** Where the library keeps its files. Default "./data". */
+    dataDir?: string;
+    /** Users backend. Default: `<dataDir>/users.json`. */
+    store?: UserStore;
+    /** Replay and revocation backend. Default: `<dataDir>/state.json`. */
+    state?: StateStore;
+    /** Signs sessions and nonces. Default: generated into `<dataDir>/session-secret`. */
+    sessionSecret?: string;
+    /** A name for this server among several that have one `sessionSecret` and
+     *  cannot share a `state` store. A nonce is then accepted only by the server
+     *  that issued it; sessions stay valid on all of them. */
+    serverId?: string;
+    session?: SessionConfig;
+    /** Limit on sign-in and launch attempts. false turns it off. */
+    rateLimit?: RateLimitConfig | false;
+    /** The site's part of a sign-in, before the answer goes out. */
+    onSignIn?: SignInHook;
+    register?: RegisterConfig;
+    visitor?: VisitorConfig;
+    /** Import the userid's beagles.eth record after sign-in. true, or the gateway and cache time. */
+    importProfile?: boolean | {
+        gateway?: string;
+        ttlHours?: number;
+    };
+    /** What the routes return as `user`. Default: the library's own fields, none of the site's. */
+    publicUser?: (user: UserRecord) => Record<string, unknown>;
+    /** The site's own Carrier identity. Omit when the site only needs sign-in. */
+    agent?: AgentConfig;
+    /** Warnings and errors. Default: `console.warn`. */
+    log?: (message: string) => void;
+}
+export interface BeagleService {
+    users: Users;
+    auth: Auth;
+    /** Present when `agent` was configured. */
+    agent?: Agent;
+    /** Framework-neutral: `({ method, path, headers, body }) → { status, headers, body }`. */
+    handle: RouteHandler;
+    /** The same, one function per route. */
+    handlers: Handlers;
+    /** For `http.createServer(...)`. Paths outside the prefix answer 404. */
+    nodeHandler(opts?: AdapterOptions): NodeHandler;
+    /** For `app.use(...)` in Express. Paths outside the prefix go to `next()`. */
+    expressHandler(opts?: AdapterOptions): NodeHandler;
+    /** For `pages/api/auth/[...beagle].js` in Next.js: `export default svc.nextApiHandler()`. */
+    nextApiHandler(opts?: AdapterOptions): NodeHandler;
+    /** One route as a `(req, res)` handler, whatever path it is mounted on: for
+     *  a site that gives each route its own file (beside NextAuth's catch-all,
+     *  or under names of its own). */
+    route(name: RouteName): NodeHandler;
+    /** For Web `Request`/`Response` hosts, such as Next.js App Router route handlers. */
+    fetchHandler(opts?: AdapterOptions): (request: Request) => Promise<Response>;
+    /** Stop the agent and timers. */
+    close(): Promise<void>;
+}
+/** A service that is created on first use and kept for the life of the
+ *  process, whoever asks for it and however often the module that asks is
+ *  evaluated. Nothing here throws at the caller for a service that cannot
+ *  start, except `ready()`. */
+export interface SharedBeagleService {
+    /** The service. Rejects when it cannot be created (a malformed `origins`
+     *  entry, a users file that does not parse); the failure is not kept, the
+     *  next call tries again. Await it at start to find a bad configuration
+     *  before the first request. */
+    ready(): Promise<BeagleService>;
+    /** `auth.authenticate` of the service. Never rejects: when the service
+     *  cannot start it answers `ok: false`, status 500. */
+    authenticate(req: HeadersCarrier, opts?: AuthenticateOptions): Promise<AuthResult>;
+    /** As on the service; they answer 500 `server-error` while it cannot start. */
+    handle: RouteHandler;
+    route(name: RouteName): NodeHandler;
+    nodeHandler(opts?: AdapterOptions): NodeHandler;
+    expressHandler(opts?: AdapterOptions): NodeHandler;
+    nextApiHandler(opts?: AdapterOptions): NodeHandler;
+    fetchHandler(opts?: AdapterOptions): (request: Request) => Promise<Response>;
+    /** Close the service if it was created, and forget it. */
+    close(): Promise<void>;
+}
+export interface SharedOptions {
+    /** A process may hold several services under different keys. Default "default". */
+    key?: string;
+    /** After a failed start, wait this long before trying again. Default 5000. */
+    retryMs?: number;
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/dist/users.d.ts

@@ -0,0 +1,16 @@
+import type { RegisterConfig, Users, UserStore, VisitorConfig } from "./types.js";
+import { type Logger } from "./util.js";
+export declare const DEFAULT_PROFILE_GATEWAY = "https://ens-gateway.beaglechat.workers.dev";
+export interface UsersOptions {
+    store: UserStore;
+    register?: RegisterConfig;
+    visitor?: VisitorConfig;
+    importProfile?: boolean | {
+        gateway?: string;
+        ttlHours?: number;
+    };
+    now?: () => number;
+    log?: Logger;
+    fetch?: typeof fetch;
+}
+export declare function createUsers(opts: UsersOptions): Users;