@decentnetwork/beagle-service 0.0.0-stage → 0.1.0

package/dist/stores.js

@@ -0,0 +1,69 @@
+import { atomicWriteJson, readJsonFile } from "./util.js";
+// ── users ───────────────────────────────────────────────────────────────────
+/** Users in one JSON file, `{ [userid]: record }`, rewritten atomically on
+ *  every change. The whole table is held in memory; good for a site with up to
+ *  some tens of thousands of users and one server process. */
+export function jsonFileUserStore(file) {
+    const users = new Map(Object.entries(readJsonFile(file, {})));
+    const flush = () => atomicWriteJson(file, Object.fromEntries(users));
+    return {
+        get: (userid) => {
+            const u = users.get(userid);
+            return u ? structuredClone(u) : null;
+        },
+        put: (user) => {
+            users.set(user.userid, structuredClone(user));
+            flush();
+        },
+        list: () => [...users.values()].map((u) => structuredClone(u)),
+    };
+}
+/** Users in memory; gone when the process ends. For tests. */
+export function memoryUserStore() {
+    const users = new Map();
+    return {
+        get: (userid) => {
+            const u = users.get(userid);
+            return u ? structuredClone(u) : null;
+        },
+        put: (user) => void users.set(user.userid, structuredClone(user)),
+        list: () => [...users.values()].map((u) => structuredClone(u)),
+    };
+}
+function setStore(load, save, now) {
+    const sets = load();
+    const prune = () => {
+        const t = now();
+        for (const ns of Object.keys(sets)) {
+            for (const [k, exp] of Object.entries(sets[ns]))
+                if (exp < t)
+                    delete sets[ns][k];
+        }
+    };
+    return {
+        addOnce(ns, key, expiresAt) {
+            prune();
+            const set = (sets[ns] ??= {});
+            if (Object.prototype.hasOwnProperty.call(set, key))
+                return false;
+            set[key] = expiresAt;
+            // Written before the answer goes out: a restart must not forget it.
+            save(sets);
+            return true;
+        },
+        has(ns, key) {
+            const exp = sets[ns]?.[key];
+            return exp !== undefined && exp >= now();
+        },
+    };
+}
+/** Used nonces, used launch assertions and revoked sessions in one JSON file,
+ *  written atomically before each answer. One server process. */
+export function jsonFileStateStore(file, now = Date.now) {
+    return setStore(() => readJsonFile(file, {}), (s) => atomicWriteJson(file, s), now);
+}
+/** The same in memory. A restart forgets it, which reopens launch replay for
+ *  two minutes; for tests. */
+export function memoryStateStore(now = Date.now) {
+    return setStore(() => ({}), () => { }, now);
+}

package/dist/types.d.ts

@@ -0,0 +1,496 @@
+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;
+    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;
+}
+/** Where users are kept. Implement these three calls for Postgres, sqlite or
+ *  anything else. `put` receives the whole record and must store all of it,
+ *  including fields it does not recognise. */
+export interface UserStore {
+    get(userid: string): Promise<UserRecord | null> | UserRecord | null;
+    put(user: UserRecord): 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;
+    }];
+    /** 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;
+    }): 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;
+}
+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" | "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;
+    };
+}
+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;
+    /** Check a `decent-auth` assertion: origin, nonce (consumed either way), signature. */
+    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. */
+    authenticate(req: HeadersCarrier, opts?: {
+        allowUnregistered?: boolean;
+        touch?: boolean;
+    }): 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;
+}
+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 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. */
+    origins: string[];
+    /** 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;
+    session?: SessionConfig;
+    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;
+    /** 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>;
+}

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;