@sovereignfs/sdk 1.25.0 → 2.0.1

package/dist/next.d.ts

@@ -0,0 +1,37 @@
+import { Session } from './index.js';
+import { Sovereign } from './index.js';
+
+type NextAuthOptions = {
+    /** Where the route is mounted. It must match the SDK's `redirectPath` (`/auth/callback`) and `postLogoutPath`. `/auth` unless changed. */
+    basePath?: string;
+    /** Where a person goes when a sign-in fails. `/` with `?error=signin` unless changed. */
+    errorPath?: string;
+    /**
+     * Deletes what the app holds of a person who deleted their account, and mounts `/auth/account-deleted` for core to tell it so (sdk §9.1). Without
+     * it that address is not there. It must be safe to run twice, and it must not resolve until the data is gone.
+     */
+    onAccountDeleted?: (person: {
+        readonly sub: string;
+    }) => Promise<void> | void;
+};
+type RouteHandler = (request: Request) => Promise<Response>;
+/**
+ * Binds the SDK's sign-in to Next.js (sdk §9): the route handlers for `/auth/login`, `/auth/callback`, `/auth/logout` and
+ * `/auth/backchannel-logout` (and `/auth/account-deleted` when `onAccountDeleted` is given), and the session as a Server Component, route or action reads it. Mount the handlers once:
+ *
+ *   // app/auth/[action]/route.ts
+ *   export const { GET, POST } = nextAuth(sv).handlers;
+ *
+ * `next` is an optional peer dependency of the SDK, and this is the only entry that uses it.
+ */
+declare function nextAuth(sv: Sovereign, options?: NextAuthOptions): {
+    handlers: {
+        GET: RouteHandler;
+        POST: RouteHandler;
+    };
+    getSession: () => Promise<Session | null>;
+    requireSession: (returnTo?: string) => Promise<Session>;
+};
+
+export { nextAuth };
+export type { NextAuthOptions };

package/dist/next.js

@@ -0,0 +1,68 @@
+import {
+  SignInError
+} from "./chunk-NYL4LLXF.js";
+
+// src/next/index.ts
+import { cookies } from "next/headers";
+import { redirect } from "next/navigation";
+function nextAuth(sv, options = {}) {
+  const base = (options.basePath ?? "/auth").replace(/\/+$/, "");
+  const errorPath = options.errorPath ?? "/?error=signin";
+  const go = (url, setCookies, status = 303) => {
+    const headers = new Headers({ location: url, "cache-control": "no-store" });
+    for (const cookie of setCookies) headers.append("set-cookie", cookie);
+    return new Response(null, { status, headers });
+  };
+  const actionOf = (request) => {
+    const path = new URL(request.url).pathname;
+    return path.startsWith(`${base}/`) ? path.slice(base.length + 1).replace(/\/+$/, "") : "";
+  };
+  const GET = async (request) => {
+    switch (actionOf(request)) {
+      case "login": {
+        const returnTo = new URL(request.url).searchParams.get("returnTo") ?? void 0;
+        const step = await sv.auth.beginSignIn(returnTo ? { returnTo } : {});
+        return go(step.url, step.setCookies, 302);
+      }
+      case "callback": {
+        try {
+          const done = await sv.auth.completeSignIn(request);
+          return go(done.returnTo, done.setCookies);
+        } catch (error) {
+          if (!(error instanceof SignInError)) throw error;
+          return go(errorPath, []);
+        }
+      }
+      default:
+        return new Response("Not found", { status: 404 });
+    }
+  };
+  const POST = async (request) => {
+    switch (actionOf(request)) {
+      case "logout": {
+        const step = await sv.auth.signOut(request);
+        return go(step.url, step.setCookies);
+      }
+      case "backchannel-logout":
+        return sv.auth.handleBackChannelLogout(request);
+      case "account-deleted":
+        return options.onAccountDeleted ? sv.auth.handleAccountDeleted(request, options.onAccountDeleted) : new Response("Not found", { status: 404 });
+      default:
+        return new Response("Not found", { status: 404 });
+    }
+  };
+  const getSession = async () => {
+    const store = await cookies();
+    const request = new Request(sv.links.profile, { headers: { cookie: store.toString() } });
+    return sv.auth.getSession(request);
+  };
+  const requireSession = async (returnTo = "/") => {
+    const session = await getSession();
+    if (session) return session;
+    return redirect(`${base}/login?returnTo=${encodeURIComponent(returnTo)}`);
+  };
+  return { handlers: { GET, POST }, getSession, requireSession };
+}
+export {
+  nextAuth
+};

package/dist/session-DJl2XYMc.d.ts

@@ -0,0 +1,44 @@
+/**
+ * What the app keeps for the SDK's sign-in (sdk §9.1). The app owns its data, so the SDK ships no store outside `/testing`; a
+ * database row or a cache entry with an expiry is enough.
+ */
+type StoredRecord = {
+    kind: 'session' | 'pending' | 'seen';
+    /** Whose session it is, so a logout notice naming only the person can end every one. */
+    sub?: string;
+    /** The core session it belongs to, so a logout notice can end just it. */
+    sid?: string;
+    /** What the SDK keeps; the store keeps it as it is. */
+    data: Record<string, unknown>;
+};
+interface SessionStore {
+    /** The record, or nothing when there is none or it has expired. A store MUST NOT return a record after its `expiresAt`. */
+    get(id: string): Promise<StoredRecord | undefined> | StoredRecord | undefined;
+    set(id: string, record: StoredRecord, expiresAt: number): Promise<void> | void;
+    delete(id: string): Promise<void> | void;
+    /** Removes every session of a person (`sub`), or the ones of one core session (`sid`). */
+    deleteMatching(match: {
+        sub?: string;
+        sid?: string;
+    }): Promise<void> | void;
+}
+/** A signed-in person, as the app sees them (sdk §9). The claims are those of the scopes granted. */
+type Session = {
+    /** Who the person is. It is stable: identify a person by it and by nothing else. */
+    readonly sub: string;
+    /** The core session this one belongs to, when core gave one. */
+    readonly sid: string | undefined;
+    /** What the ID token said: `name`, `email`, `picture`, and so on, for the scopes granted. */
+    readonly claims: Readonly<Record<string, unknown>>;
+    /** The scopes granted. */
+    readonly scopes: readonly string[];
+    /** The roles core gave a trusted app, or none. */
+    readonly roles: readonly string[];
+    /** When this session ends, in milliseconds. */
+    readonly expiresAt: number;
+};
+/** True when core said the person has this role. An app that was not given `roles` has none (sdk §9). */
+declare function hasRole(session: Pick<Session, 'roles'>, role: string): boolean;
+
+export { hasRole as h };
+export type { Session as S, SessionStore as a, StoredRecord as b };

package/dist/sovereign-CazGKEVc.d.ts

@@ -0,0 +1,517 @@
+import { a as SessionStore, S as Session } from './session-DJl2XYMc.js';
+
+/**
+ * How it looks. It changes nothing else.
+ */
+type NotificationCategory = 'info' | 'success' | 'warning' | 'error';
+type Notification = {
+    id: string;
+    title: string;
+    body: string | null;
+    url: string | null;
+    category: NotificationCategory;
+    createdAt: string;
+    readAt: string | null;
+    expiresAt: string;
+};
+type NotificationCount = {
+    count: number;
+};
+type DirectoryUser = {
+    /**
+     * The person's stable identifier, the same `sub` an ID token carries. Never reused.
+     */
+    sub: string;
+    name: string;
+    /**
+     * The address of their picture, or null when they have none.
+     */
+    picture: string | null;
+};
+type DirectoryUserStatus = {
+    sub: string;
+    name: string;
+    picture: string | null;
+    /**
+     * False for a deactivated account, which cannot sign in.
+     */
+    active: boolean;
+};
+type InstanceBranding = {
+    /**
+     * The instance's name.
+     */
+    name: string;
+    /**
+     * The instance's own address, which is also its issuer.
+     */
+    url: string;
+    logo: {
+        /**
+         * A logo for a light page. When only one logo is set it is given for both.
+         */
+        light: string | null;
+        /**
+         * A logo for a dark page.
+         */
+        dark: string | null;
+    };
+    favicon: string | null;
+    /**
+     * What this core serves, so an app can tell a capability it lacks from a failure. A core that does not
+     * publish this field serves the Directory and the instance document, and nothing else.
+     */
+    api: {
+        /**
+         * The API versions served, such as `v1`.
+         */
+        versions: string[];
+        /**
+         * The groups of calls served, such as `directory`. A capability is listed when every call of it is
+         * served.
+         */
+        capabilities: ('directory' | 'notifications' | 'email' | 'activity')[];
+    };
+};
+
+/** What each operation takes and answers with. */
+interface Operations {
+    /**
+     * Dismiss all of this app's notifications
+     */
+    dismissAllNotifications: {
+        request: undefined;
+        response: NotificationCount;
+    };
+    /**
+     * Dismiss one notification
+     */
+    dismissNotification: {
+        request: {
+            params: {
+                id: string;
+            };
+        };
+        response: Notification;
+    };
+    /**
+     * Find one person by their whole email address
+     */
+    findDirectoryUserByEmail: {
+        request: {
+            query: {
+                email: string;
+            };
+        };
+        response: DirectoryUser;
+    };
+    /**
+     * The instance's name, logos and favicon
+     */
+    getInstanceBranding: {
+        request: undefined;
+        response: InstanceBranding;
+    };
+    /**
+     * The notifications this app sent a person
+     */
+    listNotifications: {
+        request: {
+            query?: {
+                unread?: boolean;
+                limit?: number;
+            };
+        };
+        response: {
+            notifications: Notification[];
+        };
+    };
+    /**
+     * Record something about a person
+     */
+    logActivity: {
+        request: {
+            body: {
+                /**
+                 * The person's `sub`.
+                 */
+                to: string;
+                summary: string;
+                link?: string;
+                /**
+                 * When it happened. Now when not given.
+                 */
+                at?: string;
+                key?: string;
+            };
+        };
+        response: {
+            id: string;
+        };
+    };
+    /**
+     * Mark all of this app's notifications read
+     */
+    markAllNotificationsRead: {
+        request: undefined;
+        response: NotificationCount;
+    };
+    /**
+     * Mark one notification read
+     */
+    markNotificationRead: {
+        request: {
+            params: {
+                id: string;
+            };
+        };
+        response: Notification;
+    };
+    /**
+     * Look people up by their `sub`
+     */
+    resolveDirectoryUsers: {
+        request: {
+            body: {
+                /**
+                 * The `sub` of each person. 1 to 100, each at most 255 characters.
+                 */
+                subs: string[];
+            };
+        };
+        response: {
+            users: DirectoryUserStatus[];
+        };
+    };
+    /**
+     * Search for people by name
+     */
+    searchDirectoryUsers: {
+        request: {
+            query: {
+                q: string;
+                limit?: number;
+            };
+        };
+        response: {
+            users: DirectoryUser[];
+        };
+    };
+    /**
+     * Email a person
+     */
+    sendEmail: {
+        request: {
+            body: {
+                /**
+                 * The person's `sub`.
+                 */
+                to: string;
+                subject: string;
+                /**
+                 * Plain text. Line breaks are kept; nothing is read as markup.
+                 */
+                body: string;
+                /**
+                 * One link, `https`, on the origin of one of the app's registered addresses.
+                 */
+                link?: string;
+                /**
+                 * A send with the same key for the same person within a day is the same send.
+                 */
+                key?: string;
+            };
+        };
+        response: {
+            id: string;
+        };
+    };
+    /**
+     * Tell a person something
+     */
+    sendNotification: {
+        request: {
+            body: {
+                /**
+                 * The person's `sub`.
+                 */
+                to: string;
+                title: string;
+                body?: string;
+                /**
+                 * Where choosing it goes. `https`, on the origin of one of the app's registered addresses.
+                 */
+                url?: string;
+                category?: NotificationCategory;
+                /**
+                 * At most 90 days on. 30 days on when not given.
+                 */
+                expiresAt?: string;
+                key?: string;
+            };
+        };
+        response: {
+            id: string;
+        };
+    };
+}
+
+/** What the SDK tells an app's logger about a request: the operation, the status and how long it took. Never a token or a person. */
+type LogEvent = {
+    operation: string;
+    /** The HTTP status, or `error` when there was none. */
+    status: number | 'error';
+    durationMs: number;
+};
+type Logger = (event: LogEvent) => void;
+/** The clock, sleep and chance the transport uses, so a test controls all three. */
+type Environment = {
+    now: () => number;
+    sleep: (ms: number) => Promise<void>;
+    random: () => number;
+};
+type TransportOptions = {
+    fetch?: typeof fetch;
+    timeoutMs?: number;
+    logger?: Logger;
+    environment?: Environment;
+};
+/** What a request is, to the transport: its name for the logger, whether it may be sent again, and when its call must be over. */
+type Meta = {
+    operation: string;
+    safeToRepeat: boolean;
+    deadline: number;
+};
+/** The deadline of one call: everything it does, a refresh and a version check included, must fit in the overall limit. */
+type Deadline = number;
+/**
+ * Sends requests to core (sdk §6): every request has a timeout; a failure to get a usable answer (a network failure, a
+ * timeout or a 5xx) is a `CoreUnavailableError`, after at most two more tries when the request is safe to repeat, all
+ * inside the call's deadline; a 429 is tried once more after `Retry-After` only if that fits. Nothing else is repeated.
+ */
+declare class Transport {
+    #private;
+    constructor(options?: TransportOptions);
+    get environment(): Environment;
+    get timeoutMs(): number;
+    /** A deadline for a call that starts now. */
+    deadline(): Deadline;
+    /** `fetch` for one request of an operation, retrying as the specification says. */
+    send(input: RequestInfo | URL, init: RequestInit, meta: Meta): Promise<Response>;
+}
+
+/**
+ * What an app gives the SDK to keep a person's refresh token (sdk §5.1). The SDK ships none, since the app owns its data.
+ *
+ * Core rotates a refresh token on every use and treats one used twice as stolen, so the store must not lose a rotation.
+ */
+interface TokenStore {
+    /** The person's refresh token, or nothing when they have none. */
+    read(sub: string): Promise<string | undefined> | string | undefined;
+    /**
+     * Stores `next` in place of `previous`, atomically: it MUST NOT store when the stored token is no longer `previous`, as
+     * with a database's conditional update. Resolves `true` when it stored `next`, and `false` (or rejects) when it did not.
+     * `previous` is `undefined` for a person with no token yet.
+     */
+    write(sub: string, next: string, previous: string | undefined): Promise<boolean> | boolean;
+    /**
+     * Runs `work` while no other process holds the lock for this person. An app that runs more than one process MUST give
+     * one: two processes sending the same refresh token are indistinguishable from theft (sdk §5.1).
+     */
+    lock?<T>(sub: string, work: () => Promise<T>): Promise<T>;
+    /**
+     * Forgets the person's refresh token. Optional: the SDK calls it when core says the person deleted their account (sdk §9.1), and
+     * an app whose store has no such call deletes the token in its own handler.
+     */
+    delete?(sub: string): Promise<void> | void;
+}
+
+type AuthOptions = {
+    appUrl: string;
+    coreUrl: string;
+    clientId: string;
+    clientSecret: string;
+    transport: Transport;
+    sessionStore: SessionStore;
+    /** Where a refresh token is kept, so the app can call as the person it signed in (sdk §5.1). */
+    tokenStore: TokenStore | undefined;
+    /** What the app asks to see. `offline_access` is what lets it call core as the person later. */
+    scopes: readonly string[];
+    /** The app's callback path. */
+    redirectPath: string;
+    /** Where core sends the person after signing out; registered with core. */
+    postLogoutPath: string;
+    /** How long a session lasts at most, in seconds. */
+    sessionSeconds: number | undefined;
+};
+/** What to do next after a step of signing in or out: where to send the person, and the cookies to set. */
+type Step = {
+    url: string;
+    setCookies: string[];
+};
+/**
+ * Signing people in through core with `openid-client`, and ending sessions (sdk §9). Framework-neutral: it takes a web
+ * `Request` and returns data and `Set-Cookie` values. It keeps nothing itself: the state of a sign-in and the sessions are
+ * records in the app's store.
+ */
+declare class Auth {
+    #private;
+    constructor(options: AuthOptions);
+    /** The app's own callback address, which must be registered with core. */
+    get redirectUri(): string;
+    /** The address core sends the person to after signing out, which must be registered with core. */
+    get postLogoutRedirectUri(): string;
+    /** Starts a sign-in: the address to send the person to, and the cookie that names what to remember. */
+    beginSignIn(options?: {
+        returnTo?: string;
+    }): Promise<Step>;
+    /** Finishes a sign-in at the callback: checks what came back, and makes the session. */
+    completeSignIn(request: Request): Promise<{
+        session: Session;
+        returnTo: string;
+        setCookies: string[];
+    }>;
+    /** The current session, or nothing. It makes no call to core: the session is the app's own. */
+    getSession(request: Request): Promise<Session | null>;
+    /** The current session, or `NotAuthenticatedError`. */
+    requireSession(request: Request): Promise<Session>;
+    /**
+     * Ends the app's session and clears its cookie, and gives the address of core's sign-out, which ends the person's core
+     * session too. It ends the app's session even if the person never returns from core.
+     */
+    signOut(request: Request): Promise<Step>;
+    /** Verifies a logout token from core and ends the sessions it names (sdk §9.1). */
+    handleBackChannelLogout(request: Request): Promise<Response>;
+    /**
+     * Handles core's account-deleted notice (sdk §9.1, core-app §4.5): the person deleted their account, and the app must delete what it
+     * holds of them. The token is refused, `400` and `invalid_request`, by the rules of a logout token for its own type and event. For a
+     * good one the SDK ends the person's sessions and forgets their stored refresh token (when the token store can), runs `handler`, and
+     * answers `200` only after it has resolved. When the handler throws it answers `500` and says nothing of why, and core sends the
+     * notice again, so the handler must be safe to run twice.
+     */
+    handleAccountDeleted(request: Request, handler: (person: {
+        readonly sub: string;
+    }) => Promise<void> | void): Promise<Response>;
+}
+
+/** How an app names its settings: by the prefix `spec/env.md` defines, or one by one (an external app). */
+type SettingsSource = {
+    /** The app's prefix: `NOTES` reads `NOTES_URL`, `NOTES_CORE_URL`, `NOTES_CORE_CLIENT_ID` and `NOTES_CORE_CLIENT_SECRET`. */
+    prefix: string;
+    /** The environment to read. Defaults to `process.env`. */
+    env?: Record<string, string | undefined>;
+    /** Reads a `*_FILE` file. Defaults to the file system; a test passes its own. */
+    readFile?: (path: string) => string;
+} | {
+    appUrl: string;
+    coreUrl: string;
+    clientId: string;
+    clientSecret: string;
+};
+
+/** A person an app calls core as: what `getSession` returns has a `sub`, and so does `{ sub }`. */
+type Person = {
+    readonly sub: string;
+};
+type Name = keyof Operations;
+type Answer<K extends Name> = Operations[K]['response'];
+type Request$1<K extends Name> = Operations[K]['request'];
+/** The Directory (sdk §8): finding people on the instance. Needs the `directory` scope. */
+interface DirectoryApi {
+    searchUsers(request: NonNullable<Request$1<'searchDirectoryUsers'>>['query']): Promise<Answer<'searchDirectoryUsers'>>;
+    resolveUsers(request: NonNullable<Request$1<'resolveDirectoryUsers'>>['body']): Promise<Answer<'resolveDirectoryUsers'>>;
+    findUserByEmail(request: NonNullable<Request$1<'findDirectoryUserByEmail'>>['query']): Promise<Answer<'findDirectoryUserByEmail'>>;
+}
+/** A person's notifications from this app (sdk §8, core-app §4.1): the ones the app sent them, never another app's. */
+interface NotificationsApi {
+    list(request?: NonNullable<Request$1<'listNotifications'>>['query']): Promise<Answer<'listNotifications'>>;
+    markRead(id: string): Promise<Answer<'markNotificationRead'>>;
+    markAllRead(): Promise<Answer<'markAllNotificationsRead'>>;
+    dismiss(id: string): Promise<Answer<'dismissNotification'>>;
+    dismissAll(): Promise<Answer<'dismissAllNotifications'>>;
+}
+/** What an app can do as a person. */
+interface PersonClient {
+    readonly directory: DirectoryApi;
+    readonly notifications: NotificationsApi;
+}
+/** What an app can do as itself, with no person (sdk §4): tell a person something. */
+interface AppClient {
+    readonly notifications: {
+        /** Sends a notification. Accepted whether or not the person receives it: core says nothing of them. */
+        send(message: NonNullable<Request$1<'sendNotification'>>['body']): Promise<Answer<'sendNotification'>>;
+    };
+    readonly email: EmailApi;
+    readonly activity: ActivityApi;
+}
+/** What an app can say to a person by email, as itself (sdk §8, core-app §4.2). */
+interface EmailApi {
+    /**
+     * Emails a person named by `sub`, in the instance's own template, without being given their address. Accepted whether or not
+     * the person receives it: core says nothing of them or their address, and never reports delivery. An instance without mail does
+     * not list `email`, and this raises `NotSupportedError` without sending.
+     */
+    sendToUser(message: NonNullable<Request$1<'sendEmail'>>['body']): Promise<Answer<'sendEmail'>>;
+}
+/** What an app can note about a person, as itself (sdk §8, core-app §4.3). */
+interface ActivityApi {
+    /**
+     * Records one line about something the app did for a person named by `sub`, in the person's own activity page in core. Accepted
+     * whether or not it is kept: core says nothing of the person. There is no way to read it back, as the app or as the person.
+     */
+    log(entry: NonNullable<Request$1<'logActivity'>>['body']): Promise<Answer<'logActivity'>>;
+}
+/** What anyone can ask, with no token. */
+interface InstanceApi {
+    getBranding(): Promise<InstanceBranding>;
+}
+/** Addresses of core's own pages for a person, which the SDK offers and has no call for (sdk §9). */
+interface Links {
+    readonly profile: string;
+    readonly security: string;
+    readonly preferences: string;
+    readonly connectedApps: string;
+    readonly deleteAccount: string;
+}
+interface Sovereign {
+    /** Calls made as this person, with their token. Needs a token store. */
+    as(person: Person): PersonClient;
+    /** Calls made as the app itself. It never holds a person's token. */
+    readonly app: AppClient;
+    /** Public calls. */
+    readonly instance: InstanceApi;
+    /** Signing people in, their sessions, and signing out (sdk §9). Needs a session store. */
+    readonly auth: Auth;
+    /** Core's own pages for a person. */
+    readonly links: Links;
+}
+type SovereignOptions = SettingsSource & {
+    /** Where a person's refresh token is kept (sdk §5.1). Needed to call as a person. */
+    tokenStore?: TokenStore;
+    /** Where the app's sessions are kept (sdk §9.1). Needed to sign people in. */
+    sessionStore?: SessionStore;
+    /** What the app asks to see when it signs a person in. `openid profile email offline_access` unless changed. */
+    scopes?: string[];
+    /** The app's callback path, which must be registered with core. `/auth/callback` unless changed. */
+    redirectPath?: string;
+    /** Where core returns a person after they sign out, which must be registered with core. `/` unless changed. */
+    postLogoutPath?: string;
+    /** How long a session lasts at most, in seconds. Thirty days unless changed. */
+    sessionSeconds?: number;
+    /** Each request's timeout. 5 seconds unless changed. */
+    timeoutMs?: number;
+    /** Told the operation, status and duration of each request, and nothing else. */
+    logger?: Logger;
+    /** `fetch`, when the runtime has none or a test supplies its own. */
+    fetch?: typeof fetch;
+    /** The clock, sleep and chance, for a test. */
+    environment?: Environment;
+};
+/**
+ * Makes the SDK's client (sdk §2). It reads its settings and makes no network call, so an app starts while core is down.
+ * Make one per process.
+ */
+declare function createSovereign(options: SovereignOptions): Sovereign;
+
+export { Auth as b, createSovereign as i };
+export type { ActivityApi as A, DirectoryApi as D, EmailApi as E, InstanceApi as I, Links as L, NotificationsApi as N, Person as P, SettingsSource as S, TokenStore as T, AppClient as a, LogEvent as c, Logger as d, PersonClient as e, Sovereign as f, SovereignOptions as g, Step as h };