@sovereignfs/sdk 1.25.0 → 2.0.1

package/dist/testing.d.ts

@@ -0,0 +1,181 @@
+import { SessionStore } from './index.js';
+
+/** A person the fake core knows. */
+type FakePerson = {
+    sub: string;
+    name?: string;
+    picture?: string | null;
+    /** False for a deactivated account (the Directory returns it with `active: false`). */
+    active?: boolean;
+};
+/**
+ * How the fake core can be told to fail (sdk §11), one for each way §6 lists:
+ *
+ * - `down`: the connection is refused, as with core stopped. Nothing reaches the fake.
+ * - `lost-answer`: the request is handled and its answer never arrives. For a refresh, core has rotated the token.
+ * - `timeout`: the answer takes longer than any timeout.
+ * - `status`: core answers with this failure status (5xx is unavailable, 429 sets `Retry-After`).
+ */
+type Failure = {
+    kind: 'down';
+} | {
+    kind: 'lost-answer';
+} | {
+    kind: 'timeout';
+} | {
+    kind: 'status';
+    status: number;
+    retryAfter?: number;
+};
+/** The ways a logout token can be wrong, each of which an app must refuse. */
+type WrongLogoutToken = 'signature' | 'issuer' | 'audience' | 'expired' | 'future' | 'event' | 'nonce' | 'type' | 'no-subject' | 'no-jti';
+/** Which requests a failure applies to. */
+type Target = 'any' | 'token' | 'api' | 'instance' | 'discovery';
+type FakeCoreOptions = {
+    /** The instance's address. */
+    url?: string;
+    /** The app's credentials in this core. */
+    clientId?: string;
+    clientSecret?: string;
+    /** The clock, in milliseconds. Defaults to the real one. */
+    now?: () => number;
+    /** How long an access token lives, in seconds. 900, as core's does. */
+    accessTokenSeconds?: number;
+    /**
+     * What the instance document says is served. `undefined` is a core that publishes no `api` (an old core), and it serves
+     * the Directory only. Defaults to a core that serves the Directory.
+     */
+    api?: {
+        versions: string[];
+        capabilities: string[];
+    } | undefined;
+    /** Whether the app may ask for a token for itself. On by default. */
+    appTokens?: boolean;
+    instance?: {
+        name?: string;
+    };
+};
+/** A notification an app sent through the fake core. */
+type FakeNotification = {
+    id: string;
+    to: string;
+    title: string;
+    body?: string;
+    url?: string;
+    category?: string;
+    createdAt: number;
+    readAt: number | null;
+    dismissed: boolean;
+};
+/** An email an app sent through the fake core. Whether it was delivered is never said, here or in core. */
+type FakeEmail = {
+    id: string;
+    to: string;
+    subject: string;
+    body: string;
+    link?: string;
+    key?: string;
+    sentAt: number;
+};
+/** An entry an app recorded through the fake core. There is no call to read it back, as in core: a test reads it here. */
+type FakeActivity = {
+    id: string;
+    to: string;
+    summary: string;
+    link?: string;
+    at: number;
+    key?: string;
+    recordedAt: number;
+};
+/** One request the fake received, with nothing secret in it. `status` is 0 when it was never answered. */
+type Received = {
+    method: string;
+    path: string;
+    status: number;
+};
+type FakeCore = {
+    /** The instance's address, to give `createSovereign` as `coreUrl`. */
+    readonly url: string;
+    /** The app's credentials in this core. */
+    readonly credentials: {
+        clientId: string;
+        clientSecret: string;
+    };
+    /** Answers like core does. Give it to `createSovereign({ fetch })`: no server, no port. */
+    readonly fetch: typeof fetch;
+    /** What apps have sent through this core, in order, whether or not it was read or dismissed. */
+    readonly notificationsSent: readonly FakeNotification[];
+    /** The emails apps sent to people the fake has, in order. A send to anyone else is accepted and dropped, as core does. */
+    readonly emailsSent: readonly FakeEmail[];
+    /** What apps recorded about people the fake has, in order. A record about anyone else is accepted and dropped, as core does. */
+    readonly activityRecorded: readonly FakeActivity[];
+    /** Adds a person to the Directory. */
+    addPerson(person: FakePerson): void;
+    /** Signs a person in, and returns the refresh token an app would have stored for them. */
+    signIn(sub: string): string;
+    /** Makes the next requests fail. `times` limits how many (default: until `heal`). */
+    fail(failure: Failure, options?: {
+        target?: Target;
+        times?: number;
+    }): void;
+    /** Ends every failure. */
+    heal(): void;
+    /**
+     * The person agrees at core's sign-in page: given the address `beginSignIn` returned, this is the address core sends the
+     * browser back to, with the code and `state`. It checks the request as core does (PKCE `S256`, a registered redirect).
+     */
+    authorize(authorizationUrl: string, sub: string, options?: {
+        roles?: string[];
+    }): string;
+    /** The core session id (`sid`) of the person's latest sign-in. */
+    sessionIdOf(sub: string): string | undefined;
+    /**
+     * A signed logout token, as core sends to an app's back-channel address when a session ends (core-app §3.6.5). `wrong` makes
+     * one that is wrong in one way, for testing that an app refuses it.
+     */
+    logoutToken(who: {
+        sub?: string;
+        sid?: string;
+    }, options?: {
+        wrong?: WrongLogoutToken;
+    }): Promise<string>;
+    /**
+     * A signed account-deleted token, as core sends to an app's account-deleted address when a person who used it deleted their account
+     * (core-app §4.5). `wrong` makes one that is wrong in one way, as for `logoutToken`.
+     */
+    accountDeletedToken(who: {
+        sub: string;
+    }, options?: {
+        wrong?: WrongLogoutToken;
+    }): Promise<string>;
+    /** Ends a person's tokens, as core does when their sessions end: the next use of any is refused. */
+    revoke(sub: string): void;
+    /** Ends every access token but keeps the refresh tokens, so the next call must refresh. */
+    expireAccessTokens(): void;
+    /** What happened. */
+    readonly seen: {
+        /** Every request, in order. */
+        readonly requests: readonly Received[];
+        /** How many times a refresh token was exchanged. */
+        readonly refreshes: number;
+        /** How many times an app token was asked for. */
+        readonly appTokens: number;
+        /** How many times an already-used refresh token was sent, which core treats as theft and answers by ending the person's tokens. */
+        readonly reused: number;
+    };
+};
+/**
+ * A core for an app's tests that needs no server (sdk §11). It answers the contract's operations and the token endpoint
+ * the way core does, including rotating a refresh token on every use and ending a person's tokens when one is used twice,
+ * and it can be told to fail in each way the specification lists. The SDK's own tests check its answers against the
+ * contract.
+ */
+declare function createFakeCore(options?: FakeCoreOptions): FakeCore;
+/**
+ * A session store for an app's tests (sdk §9.1): records in memory, with the expiry the contract asks for. An app's own is a
+ * database table or a cache; this is only for tests.
+ */
+declare function memorySessionStore(now?: () => number): SessionStore;
+
+export { createFakeCore, memorySessionStore };
+export type { Failure, FakeActivity, FakeCore, FakeCoreOptions, FakeEmail, FakeNotification, FakePerson, Received, Target, WrongLogoutToken };