@sasjs/api 0.2.1 → 0.3.0

package/build/esm/identity/memory-store.d.ts

@@ -0,0 +1,51 @@
+/**
+ * An `IdentityStore` over maps, for tests and for a host with no database.
+ *
+ * Tokens are opaque strings this store can look up, which is the shape the
+ * browser build needs: no signing key, and nothing in the string a client can
+ * read. They are minted from the platform's cryptographic source and carry the
+ * client's lifetime, so a guessed string buys nothing and an old one stops
+ * resolving. A host with real credentials - a server - supplies its own store
+ * with JWTs, bcrypt and a database behind it.
+ */
+import type { IdentityClient, IdentityStore, IdentityUser, Subject, TokenPair } from './types.js';
+import { type IdentityFixture } from './fixture.js';
+/**
+ * Whether a token minted for one subject names the same user and client.
+ *
+ * The fixture can declare a token that outlives the map it is seeded into, so
+ * the read paths compare rather than trust the reference.
+ */
+export declare class MemoryIdentityStore implements IdentityStore {
+    private readonly users;
+    private readonly passwords;
+    private readonly clients;
+    private readonly pairs;
+    private readonly access;
+    private readonly refresh;
+    private readonly codes;
+    private readonly claimed;
+    constructor(fixture?: IdentityFixture);
+    userByName(username: string): Promise<IdentityUser | undefined>;
+    userById(uid: string): Promise<IdentityUser | undefined>;
+    /** A fixture holds the password in clear, so the check is an equality. */
+    passwordMatches(user: IdentityUser, password: string): Promise<boolean>;
+    client(clientId: string): Promise<IdentityClient | undefined>;
+    issue(subject: Subject, client: IdentityClient): Promise<TokenPair>;
+    /**
+     * A token names its subject only while that subject's CURRENT pair holds it.
+     * The server verifies a token against the pair saved for the user and client,
+     * so a logged-out or rotated token stops working there too; without the same
+     * check here, the browser host would honour a token the server had revoked.
+     */
+    readAccess(token: string): Promise<Subject | undefined>;
+    readRefresh(token: string): Promise<Subject | undefined>;
+    private current;
+    pairFor(subject: Subject): Promise<TokenPair | undefined>;
+    savePair(subject: Subject, pair: TokenPair): Promise<void>;
+    deletePair(subject: Subject): Promise<void>;
+    issueCode(subject: Subject): Promise<string>;
+    readCode(code: string): Promise<Subject | undefined>;
+    claimCode(code: string): Promise<boolean>;
+}
+//# sourceMappingURL=memory-store.d.ts.map

package/build/esm/identity/memory-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory-store.d.ts","sourceRoot":"","sources":["../../../src/identity/memory-store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,KAAK,EACV,cAAc,EACd,aAAa,EACb,YAAY,EACZ,OAAO,EACP,SAAS,EACV,MAAM,YAAY,CAAA;AACnB,OAAO,EAGL,KAAK,eAAe,EACrB,MAAM,cAAc,CAAA;AAyDrB;;;;;GAKG;AACH,qBAAa,mBAAoB,YAAW,aAAa;IACvD,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAqB;IAC3C,OAAO,CAAC,QAAQ,CAAC,SAAS,CAA4B;IACtD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAoC;IAC5D,OAAO,CAAC,QAAQ,CAAC,KAAK,CAA+B;IACrD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA4B;IACnD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA4B;IACpD,OAAO,CAAC,QAAQ,CAAC,KAAK,CAA4B;IAClD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAoB;gBAEhC,OAAO,GAAE,eAAkC;IAsDjD,UAAU,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,GAAG,SAAS,CAAC;IAI/D,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,GAAG,SAAS,CAAC;IAI9D,0EAA0E;IACpE,eAAe,CACnB,IAAI,EAAE,YAAY,EAClB,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,OAAO,CAAC;IAIb,MAAM,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,GAAG,SAAS,CAAC;IAI7D,KAAK,CAAC,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,cAAc,GAAG,OAAO,CAAC,SAAS,CAAC;IAoBzE;;;;;OAKG;IACG,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,GAAG,SAAS,CAAC;IAIvD,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,GAAG,SAAS,CAAC;IAI9D,OAAO,CAAC,OAAO;IAeT,OAAO,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,SAAS,GAAG,SAAS,CAAC;IAIzD,QAAQ,CAAC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC;IAI1D,UAAU,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC;IAI3C,SAAS,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,MAAM,CAAC;IAS5C,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,GAAG,SAAS,CAAC;IAIpD,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;CAKhD"}

package/build/esm/identity/memory-store.js

@@ -0,0 +1,175 @@
+import { DEFAULT_IDENTITY, IDENTITY_FORMAT } from './fixture.js';
+import { ApiError } from '../types.js';
+const keyOf = (subject) => `${subject.userId}|${subject.clientId}`;
+/**
+ * Opaque identity strings, from the platform's cryptographic source.
+ *
+ * These strings are credentials: whoever holds one is the caller it names. A
+ * counter or `Math.random` is a sequence a reader can reproduce, so it would
+ * let one caller name another - the store is small and demo-shaped, but a token
+ * that can be guessed is not a demo quirk, it is an authentication bypass.
+ *
+ * `globalThis.crypto` is present in every browser and in Node from 19, which is
+ * the same reach the rest of this package has (no node imports, so the browser
+ * build bundles it unchanged).
+ */
+const randomHex = (bytes) => {
+    const source = globalThis.crypto;
+    if (!source)
+        throw new ApiError(500, 'This host has no Web Crypto (`globalThis.crypto`), so it cannot mint an unguessable identity string.');
+    const buffer = new Uint8Array(bytes);
+    source.getRandomValues(buffer);
+    return Array.from(buffer, (byte) => byte.toString(16).padStart(2, '0')).join('');
+};
+/**
+ * How long a code buys tokens, in seconds.
+ *
+ * The same lifetime `sasjs/server` signs into its auth code JWT, so a code a
+ * mock issues and one a server issues age out together.
+ */
+const CODE_LIFETIME_SECONDS = 30;
+const live = (issued, now) => issued && (issued.expiresAt === undefined || issued.expiresAt > now)
+    ? issued.subject
+    : undefined;
+/**
+ * Whether a token minted for one subject names the same user and client.
+ *
+ * The fixture can declare a token that outlives the map it is seeded into, so
+ * the read paths compare rather than trust the reference.
+ */
+export class MemoryIdentityStore {
+    constructor(fixture = DEFAULT_IDENTITY) {
+        this.users = [];
+        this.passwords = new Map();
+        this.clients = new Map();
+        this.pairs = new Map();
+        this.access = new Map();
+        this.refresh = new Map();
+        this.codes = new Map();
+        this.claimed = new Set();
+        if (fixture.format !== IDENTITY_FORMAT)
+            throw new ApiError(500, `The identity fixture states format ${String(fixture.format)}; this store reads ${IDENTITY_FORMAT}.`);
+        for (const user of fixture.users) {
+            this.users.push({
+                uid: user.uid,
+                username: user.username,
+                displayName: user.displayName,
+                isAdmin: user.isAdmin,
+                isActive: user.isActive,
+                needsToUpdatePassword: user.needsToUpdatePassword
+            });
+            this.passwords.set(user.uid, user.password);
+        }
+        for (const client of fixture.clients)
+            this.clients.set(client.clientId, {
+                clientId: client.clientId,
+                accessTokenExpiration: client.accessTokenExpiration,
+                refreshTokenExpiration: client.refreshTokenExpiration
+            });
+        for (const token of fixture.tokens || []) {
+            const user = this.users.find((candidate) => candidate.username === token.username);
+            if (!user)
+                continue;
+            const subject = { userId: user.uid, clientId: token.clientId };
+            if (token.accessToken)
+                this.access.set(token.accessToken, { subject });
+            if (token.refreshToken)
+                this.refresh.set(token.refreshToken, { subject });
+            // a seeded token is the subject's live pair, which is what makes it
+            // authenticate: the read paths check the pair, not the token alone
+            if (token.accessToken && token.refreshToken)
+                this.pairs.set(keyOf(subject), {
+                    accessToken: token.accessToken,
+                    refreshToken: token.refreshToken
+                });
+        }
+        for (const code of fixture.codes || []) {
+            const user = this.users.find((candidate) => candidate.username === code.username);
+            if (!user)
+                continue;
+            this.codes.set(code.code, {
+                subject: { userId: user.uid, clientId: code.clientId }
+            });
+        }
+    }
+    async userByName(username) {
+        return this.users.find((user) => user.username === username);
+    }
+    async userById(uid) {
+        return this.users.find((user) => user.uid === uid);
+    }
+    /** A fixture holds the password in clear, so the check is an equality. */
+    async passwordMatches(user, password) {
+        return this.passwords.get(user.uid) === password;
+    }
+    async client(clientId) {
+        return this.clients.get(clientId);
+    }
+    async issue(subject, client) {
+        // The lifetimes are the client's, recorded against the instant of issue: a
+        // token's expiry is a fact about this pair, so the read paths can answer
+        // "invalid or expired" rather than carrying a number nothing compares.
+        const issuedAt = Date.now();
+        const pair = {
+            accessToken: `access-${randomHex(16)}`,
+            refreshToken: `refresh-${randomHex(16)}`
+        };
+        this.access.set(pair.accessToken, {
+            subject,
+            expiresAt: issuedAt + client.accessTokenExpiration * 1000
+        });
+        this.refresh.set(pair.refreshToken, {
+            subject,
+            expiresAt: issuedAt + client.refreshTokenExpiration * 1000
+        });
+        return pair;
+    }
+    /**
+     * A token names its subject only while that subject's CURRENT pair holds it.
+     * The server verifies a token against the pair saved for the user and client,
+     * so a logged-out or rotated token stops working there too; without the same
+     * check here, the browser host would honour a token the server had revoked.
+     */
+    async readAccess(token) {
+        return this.current(token, this.access, 'accessToken');
+    }
+    async readRefresh(token) {
+        return this.current(token, this.refresh, 'refreshToken');
+    }
+    current(token, issued, kind) {
+        const entry = issued.get(token);
+        if (!entry)
+            return undefined;
+        const subject = live(entry, Date.now());
+        if (!subject)
+            return undefined;
+        const pair = this.pairs.get(keyOf(subject));
+        return pair && pair[kind] === token ? subject : undefined;
+    }
+    async pairFor(subject) {
+        return this.pairs.get(keyOf(subject));
+    }
+    async savePair(subject, pair) {
+        this.pairs.set(keyOf(subject), pair);
+    }
+    async deletePair(subject) {
+        this.pairs.delete(keyOf(subject));
+    }
+    async issueCode(subject) {
+        const code = `code-${randomHex(16)}`;
+        this.codes.set(code, {
+            subject,
+            expiresAt: Date.now() + CODE_LIFETIME_SECONDS * 1000
+        });
+        return code;
+    }
+    async readCode(code) {
+        return live(this.codes.get(code), Date.now());
+    }
+    async claimCode(code) {
+        if (this.claimed.has(code) || !this.codes.has(code))
+            return false;
+        this.claimed.add(code);
+        return true;
+    }
+}

package/build/esm/identity/service.d.ts

@@ -0,0 +1,48 @@
+import type { IdentityStore, IdentityUser, Subject, TokenPair } from './types.js';
+export interface LoginResult {
+    loggedIn: boolean;
+    user: {
+        uid: string;
+        username: string;
+        displayName: string;
+        isAdmin: boolean;
+        needsToUpdatePassword: boolean;
+    };
+}
+export interface SessionResult {
+    uid: string;
+    username: string;
+    displayName: string;
+    isAdmin: boolean;
+    needsToUpdatePassword: boolean;
+}
+export interface IdentityService {
+    /**
+     * The subject an access token names, or undefined. A host that already knows
+     * its caller - a session cookie - does not need this.
+     */
+    authenticate(token: string | undefined): Promise<Subject | undefined>;
+    login(credentials: {
+        username: string;
+        password: string;
+    }): Promise<LoginResult>;
+    /** The authorization code a signed-in caller exchanges for tokens. */
+    authorize(subject: Subject | undefined, clientId: string): Promise<string>;
+    /** The token pair an authorization code buys. */
+    token(request: {
+        clientId: string;
+        code: string;
+    }): Promise<TokenPair>;
+    /** A new pair for the caller a refresh token names. */
+    refresh(token: string | undefined): Promise<TokenPair>;
+    /** Revokes the caller's pair. Answers nothing; the route is a 204. */
+    logout(subject: Subject | undefined): Promise<void>;
+    /** The body the browser sign-out answers once the host has reset its session. */
+    logoutSession(): Promise<string>;
+    /** The caller, as `GET /SASjsApi/session` reports it. */
+    session(subject: Subject | undefined): Promise<SessionResult>;
+}
+export declare const createIdentityService: (store: IdentityStore) => IdentityService;
+/** A subject, as the session route reports it. */
+export declare const asSession: (user: IdentityUser) => SessionResult;
+//# sourceMappingURL=service.d.ts.map

package/build/esm/identity/service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"service.d.ts","sourceRoot":"","sources":["../../../src/identity/service.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EACV,aAAa,EACb,YAAY,EACZ,OAAO,EACP,SAAS,EACV,MAAM,YAAY,CAAA;AAEnB,MAAM,WAAW,WAAW;IAC1B,QAAQ,EAAE,OAAO,CAAA;IACjB,IAAI,EAAE;QACJ,GAAG,EAAE,MAAM,CAAA;QACX,QAAQ,EAAE,MAAM,CAAA;QAChB,WAAW,EAAE,MAAM,CAAA;QACnB,OAAO,EAAE,OAAO,CAAA;QAChB,qBAAqB,EAAE,OAAO,CAAA;KAC/B,CAAA;CACF;AAED,MAAM,WAAW,aAAa;IAC5B,GAAG,EAAE,MAAM,CAAA;IACX,QAAQ,EAAE,MAAM,CAAA;IAChB,WAAW,EAAE,MAAM,CAAA;IACnB,OAAO,EAAE,OAAO,CAAA;IAChB,qBAAqB,EAAE,OAAO,CAAA;CAC/B;AAED,MAAM,WAAW,eAAe;IAC9B;;;OAGG;IACH,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAAC,OAAO,GAAG,SAAS,CAAC,CAAA;IACrE,KAAK,CAAC,WAAW,EAAE;QACjB,QAAQ,EAAE,MAAM,CAAA;QAChB,QAAQ,EAAE,MAAM,CAAA;KACjB,GAAG,OAAO,CAAC,WAAW,CAAC,CAAA;IACxB,sEAAsE;IACtE,SAAS,CAAC,OAAO,EAAE,OAAO,GAAG,SAAS,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAA;IAC1E,iDAAiD;IACjD,KAAK,CAAC,OAAO,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,SAAS,CAAC,CAAA;IACtE,uDAAuD;IACvD,OAAO,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAAC,SAAS,CAAC,CAAA;IACtD,sEAAsE;IACtE,MAAM,CAAC,OAAO,EAAE,OAAO,GAAG,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IACnD,iFAAiF;IACjF,aAAa,IAAI,OAAO,CAAC,MAAM,CAAC,CAAA;IAChC,yDAAyD;IACzD,OAAO,CAAC,OAAO,EAAE,OAAO,GAAG,SAAS,GAAG,OAAO,CAAC,aAAa,CAAC,CAAA;CAC9D;AAsBD,eAAO,MAAM,qBAAqB,GAChC,OAAO,aAAa,KACnB,eAiHD,CAAA;AAEF,kDAAkD;AAClD,eAAO,MAAM,SAAS,GAAI,MAAM,YAAY,KAAG,aAM7C,CAAA"}

package/build/esm/identity/service.js

@@ -0,0 +1,137 @@
+/**
+ * The sign-in flow's decisions: what each route answers, in which order, with
+ * which wording.
+ *
+ * The transport stays with the host - a session cookie and a CSRF token on a
+ * server, whatever the browser build holds - so nothing here reads a request.
+ * A host resolves the caller (a bearer token through `authenticate`, a session
+ * it already has) and passes the subject in; the service decides whether that
+ * is enough for the operation to proceed.
+ */
+import { ApiError } from '../types.js';
+const unauthorized = () => new ApiError(401, 'Unauthorized');
+/**
+ * The subject, provided the account behind it may still hold a token.
+ *
+ * `authenticate` reads a token on every request and refuses a deactivated
+ * account; an exchange or a refresh that skipped the same check would mint a
+ * fresh pair for exactly that account, so the check sits beside every path that
+ * reaches `store.issue`.
+ */
+const liveSubject = async (store, subject) => {
+    const user = await store.userById(subject.userId);
+    if (!user || !user.isActive)
+        throw unauthorized();
+    return subject;
+};
+export const createIdentityService = (store) => ({
+    async authenticate(token) {
+        if (token === undefined)
+            return undefined;
+        const subject = await store.readAccess(token);
+        if (!subject)
+            return undefined;
+        // A token names a user who may since have been deactivated. sasjs/server
+        // checks `isActive` on every request, so a token that outlived the account
+        // must stop resolving here too - otherwise the browser host honours a
+        // caller the server would refuse.
+        const user = await store.userById(subject.userId);
+        return user && user.isActive ? subject : undefined;
+    },
+    async login({ username, password }) {
+        const user = await store.userByName(username);
+        // An unknown username and a wrong password answer with different messages
+        // on purpose: the server's login form tells the caller which one it was,
+        // and the account lockout - the defence against guessing - is the host's.
+        if (!user)
+            throw new ApiError(401, 'Username is not found.');
+        if (!(await store.passwordMatches(user, password)))
+            throw new ApiError(401, 'Invalid Password.');
+        // Checked after the password, so the answer is not a way to learn that an
+        // account exists but is switched off without knowing its password.
+        if (!user.isActive)
+            throw new ApiError(401, 'This account is not active.');
+        return {
+            loggedIn: true,
+            user: {
+                uid: user.uid,
+                username: user.username,
+                displayName: user.displayName,
+                isAdmin: user.isAdmin,
+                needsToUpdatePassword: user.needsToUpdatePassword
+            }
+        };
+    },
+    async authorize(subject, clientId) {
+        // The same answer the server's middleware gives a caller with no token: the
+        // two hosts must not describe the same refusal differently.
+        if (!subject)
+            throw unauthorized();
+        if (!(await store.client(clientId)))
+            throw new ApiError(403, 'Invalid clientId.');
+        return store.issueCode({ userId: subject.userId, clientId });
+    },
+    async token({ clientId, code }) {
+        // Read before claiming: a code presented with another client is refused
+        // with the same answer as one that does not verify, and it is not spent, so
+        // the caller can still exchange it for the client it was issued for.
+        const subject = await store.readCode(code);
+        if (!subject || subject.clientId !== clientId)
+            throw new ApiError(401, 'Invalid Auth Code');
+        // The client is read before the code is spent and before an existing pair is
+        // handed back: both the pair and the tokens it would buy belong to the
+        // client, so a client deleted since the code was issued refuses the
+        // exchange - and refuses it without consuming the code.
+        const client = await store.client(clientId);
+        if (!client)
+            throw new ApiError(401, 'Invalid clientId.');
+        const named = await liveSubject(store, subject);
+        if (!(await store.claimCode(code)))
+            throw new ApiError(401, 'Invalid Auth Code');
+        // Re-exchanging a code for the same user and client while a valid pair
+        // exists returns that pair: another tab holding the old tokens must not be
+        // signed out by a second exchange.
+        const existing = await store.pairFor(named);
+        if (existing)
+            return existing;
+        const pair = await store.issue(named, client);
+        await store.savePair(named, pair);
+        return pair;
+    },
+    async refresh(token) {
+        const subject = token === undefined ? undefined : await store.readRefresh(token);
+        if (!subject)
+            throw unauthorized();
+        const client = await store.client(subject.clientId);
+        if (!client)
+            throw new ApiError(401, 'Invalid clientId.');
+        const named = await liveSubject(store, subject);
+        const pair = await store.issue(named, client);
+        await store.savePair(named, pair);
+        return pair;
+    },
+    async logout(subject) {
+        if (!subject)
+            throw unauthorized();
+        await store.deletePair(subject);
+    },
+    async logoutSession() {
+        return 'OK!';
+    },
+    async session(subject) {
+        if (!subject)
+            throw unauthorized();
+        const user = await store.userById(subject.userId);
+        if (!user)
+            throw unauthorized();
+        return asSession(user);
+    }
+});
+/** A subject, as the session route reports it. */
+export const asSession = (user) => ({
+    uid: user.uid,
+    username: user.username,
+    displayName: user.displayName,
+    isAdmin: user.isAdmin,
+    needsToUpdatePassword: user.needsToUpdatePassword
+});

package/build/esm/identity/types.d.ts

@@ -0,0 +1,79 @@
+/**
+ * The identity the API works over, as a host supplies it.
+ *
+ * A server holds users in a database, verifies a bcrypt hash and signs JWTs; a
+ * browser build holds a seeded fixture, compares a plain-text demo password and
+ * mints opaque strings. Those differences are the host's, so they live behind
+ * this port - the statuses, the messages and the order of the checks are the
+ * service's, and both hosts run the same corpus over them.
+ */
+/** The caller a token names: a user, and the client the token was issued for. */
+export interface Subject {
+    userId: string;
+    clientId: string;
+}
+export interface IdentityUser {
+    uid: string;
+    username: string;
+    displayName: string;
+    isAdmin: boolean;
+    isActive: boolean;
+    needsToUpdatePassword: boolean;
+}
+export interface IdentityClient {
+    clientId: string;
+    /** Seconds an access token lives, as the client is configured. */
+    accessTokenExpiration: number;
+    /** Seconds a refresh token lives. */
+    refreshTokenExpiration: number;
+}
+export interface TokenPair {
+    accessToken: string;
+    refreshToken: string;
+}
+/**
+ * Users, clients, token pairs and auth codes, plus the cryptography that names
+ * a subject in a token.
+ *
+ * Minting and reading a token sit here rather than on a separate codec because
+ * they are one decision: a host that signs JWTs also verifies them against the
+ * same secret, and a host with no signing key issues opaque strings it can look
+ * up. Splitting them would let a host pair one host's minting with another's
+ * verification, which is never what anyone means.
+ */
+export interface IdentityStore {
+    userByName(username: string): Promise<IdentityUser | undefined>;
+    userById(uid: string): Promise<IdentityUser | undefined>;
+    /**
+     * Whether the password matches. The host owns the check: a bcrypt hash, a
+     * directory bind, or a fixture's declared demo password.
+     */
+    passwordMatches(user: IdentityUser, password: string): Promise<boolean>;
+    client(clientId: string): Promise<IdentityClient | undefined>;
+    /** A pair for the subject, with the client's own lifetimes. */
+    issue(subject: Subject, client: IdentityClient): Promise<TokenPair>;
+    /** The subject an access token names, or undefined when it is invalid or expired. */
+    readAccess(token: string): Promise<Subject | undefined>;
+    /** The same for a refresh token. A host may keep them in separate stores. */
+    readRefresh(token: string): Promise<Subject | undefined>;
+    /** The pair currently held for the subject, if the host keeps one. */
+    pairFor(subject: Subject): Promise<TokenPair | undefined>;
+    savePair(subject: Subject, pair: TokenPair): Promise<void>;
+    deletePair(subject: Subject): Promise<void>;
+    /** A single-use authorization code naming the subject. */
+    issueCode(subject: Subject): Promise<string>;
+    /**
+     * The subject a code names, without consuming it: authentic and unexpired,
+     * or undefined. Read first, so a code presented with the wrong client id is
+     * refused without being spent - the caller may still exchange it for the
+     * client it was issued for.
+     */
+    readCode(code: string): Promise<Subject | undefined>;
+    /**
+     * Spends a code, answering whether this call was the one that did. The first
+     * call answers true; every later call for the same string answers false,
+     * which is what makes an exchange single-use even when two requests race.
+     */
+    claimCode(code: string): Promise<boolean>;
+}
+//# sourceMappingURL=types.d.ts.map

package/build/esm/identity/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/identity/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,iFAAiF;AACjF,MAAM,WAAW,OAAO;IACtB,MAAM,EAAE,MAAM,CAAA;IACd,QAAQ,EAAE,MAAM,CAAA;CACjB;AAED,MAAM,WAAW,YAAY;IAC3B,GAAG,EAAE,MAAM,CAAA;IACX,QAAQ,EAAE,MAAM,CAAA;IAChB,WAAW,EAAE,MAAM,CAAA;IACnB,OAAO,EAAE,OAAO,CAAA;IAChB,QAAQ,EAAE,OAAO,CAAA;IACjB,qBAAqB,EAAE,OAAO,CAAA;CAC/B;AAED,MAAM,WAAW,cAAc;IAC7B,QAAQ,EAAE,MAAM,CAAA;IAChB,kEAAkE;IAClE,qBAAqB,EAAE,MAAM,CAAA;IAC7B,qCAAqC;IACrC,sBAAsB,EAAE,MAAM,CAAA;CAC/B;AAED,MAAM,WAAW,SAAS;IACxB,WAAW,EAAE,MAAM,CAAA;IACnB,YAAY,EAAE,MAAM,CAAA;CACrB;AAED;;;;;;;;;GASG;AACH,MAAM,WAAW,aAAa;IAC5B,UAAU,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,GAAG,SAAS,CAAC,CAAA;IAC/D,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,GAAG,SAAS,CAAC,CAAA;IACxD;;;OAGG;IACH,eAAe,CAAC,IAAI,EAAE,YAAY,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAA;IACvE,MAAM,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,GAAG,SAAS,CAAC,CAAA;IAC7D,+DAA+D;IAC/D,KAAK,CAAC,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,cAAc,GAAG,OAAO,CAAC,SAAS,CAAC,CAAA;IACnE,qFAAqF;IACrF,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,GAAG,SAAS,CAAC,CAAA;IACvD,6EAA6E;IAC7E,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,GAAG,SAAS,CAAC,CAAA;IACxD,sEAAsE;IACtE,OAAO,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,SAAS,GAAG,SAAS,CAAC,CAAA;IACzD,QAAQ,CAAC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAC1D,UAAU,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAC3C,0DAA0D;IAC1D,SAAS,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,MAAM,CAAC,CAAA;IAC5C;;;;;OAKG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,GAAG,SAAS,CAAC,CAAA;IACpD;;;;OAIG;IACH,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAA;CAC1C"}

package/build/esm/identity/types.js

@@ -0,0 +1,10 @@
+/**
+ * The identity the API works over, as a host supplies it.
+ *
+ * A server holds users in a database, verifies a bcrypt hash and signs JWTs; a
+ * browser build holds a seeded fixture, compares a plain-text demo password and
+ * mints opaque strings. Those differences are the host's, so they live behind
+ * this port - the statuses, the messages and the order of the checks are the
+ * service's, and both hosts run the same corpus over them.
+ */
+export {};

package/build/esm/index.d.ts

@@ -24,7 +24,14 @@ export { OVERLAY, TAG_CAPABILITIES } from './routes/overlay.js';
 export type { RouteOverlay } from './routes/overlay.js';
 export { dispatch, HANDLED_ROUTES } from './host/dispatch.js';
 export type { ApiRequest, ApiResponse, Services } from './host/dispatch.js';
+export { createIdentityService } from './identity/service.js';
+export type { IdentityService, LoginResult, SessionResult } from './identity/service.js';
+export { MemoryIdentityStore } from './identity/memory-store.js';
+export { DEFAULT_IDENTITY, IDENTITY_FORMAT, parseIdentity } from './identity/fixture.js';
+export type { IdentityFixture, IdentityFixtureClient, IdentityFixtureCode, IdentityFixtureGroup, IdentityFixturePermission, IdentityFixtureToken, IdentityFixtureUser } from './identity/fixture.js';
+export type { IdentityClient, IdentityStore, IdentityUser, Subject, TokenPair } from './identity/types.js';
 export { DRIVE_CORPUS } from './corpus/drive.js';
+export { IDENTITY_CORPUS } from './corpus/identity.js';
 export type { CorpusCase } from './corpus/drive.js';
 export { runCase, servicesFor } from './corpus/runner.js';
 export type { CaseResult } from './corpus/runner.js';

package/build/esm/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,cAAc,YAAY,CAAA;AAC1B,OAAO,EACL,kBAAkB,EAClB,mBAAmB,EACnB,OAAO,EACP,QAAQ,EACR,MAAM,EACP,MAAM,kBAAkB,CAAA;AACzB,OAAO,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAA;AACvD,YAAY,EACV,YAAY,EACZ,WAAW,EACX,YAAY,EACZ,SAAS,EACT,SAAS,EACV,MAAM,oBAAoB,CAAA;AAC3B,OAAO,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAA;AAC1D,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAA;AAChE,YAAY,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAA;AACnD,OAAO,EAAE,OAAO,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAA;AAC/D,YAAY,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAA;AACvD,OAAO,EAAE,QAAQ,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAA;AAC7D,YAAY,EAAE,UAAU,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAA;AAC3E,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAA;AAChD,YAAY,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAA;AACnD,OAAO,EAAE,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAA;AACzD,YAAY,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,cAAc,YAAY,CAAA;AAC1B,OAAO,EACL,kBAAkB,EAClB,mBAAmB,EACnB,OAAO,EACP,QAAQ,EACR,MAAM,EACP,MAAM,kBAAkB,CAAA;AACzB,OAAO,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAA;AACvD,YAAY,EACV,YAAY,EACZ,WAAW,EACX,YAAY,EACZ,SAAS,EACT,SAAS,EACV,MAAM,oBAAoB,CAAA;AAC3B,OAAO,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAA;AAC1D,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAA;AAChE,YAAY,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAA;AACnD,OAAO,EAAE,OAAO,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAA;AAC/D,YAAY,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAA;AACvD,OAAO,EAAE,QAAQ,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAA;AAC7D,YAAY,EAAE,UAAU,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAA;AAC3E,OAAO,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAA;AAC7D,YAAY,EACV,eAAe,EACf,WAAW,EACX,aAAa,EACd,MAAM,uBAAuB,CAAA;AAC9B,OAAO,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAA;AAChE,OAAO,EACL,gBAAgB,EAChB,eAAe,EACf,aAAa,EACd,MAAM,uBAAuB,CAAA;AAC9B,YAAY,EACV,eAAe,EACf,qBAAqB,EACrB,mBAAmB,EACnB,oBAAoB,EACpB,yBAAyB,EACzB,oBAAoB,EACpB,mBAAmB,EACpB,MAAM,uBAAuB,CAAA;AAC9B,YAAY,EACV,cAAc,EACd,aAAa,EACb,YAAY,EACZ,OAAO,EACP,SAAS,EACV,MAAM,qBAAqB,CAAA;AAC5B,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAA;AAChD,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAA;AACtD,YAAY,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAA;AACnD,OAAO,EAAE,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAA;AACzD,YAAY,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAA"}

package/build/esm/index.js

@@ -20,5 +20,9 @@ export { MemoryDriveStore } from './drive/memory-store.js';
 export { ROUTES, routeById, findRoute } from './routes/index.js';
 export { OVERLAY, TAG_CAPABILITIES } from './routes/overlay.js';
 export { dispatch, HANDLED_ROUTES } from './host/dispatch.js';
+export { createIdentityService } from './identity/service.js';
+export { MemoryIdentityStore } from './identity/memory-store.js';
+export { DEFAULT_IDENTITY, IDENTITY_FORMAT, parseIdentity } from './identity/fixture.js';
 export { DRIVE_CORPUS } from './corpus/drive.js';
+export { IDENTITY_CORPUS } from './corpus/identity.js';
 export { runCase, servicesFor } from './corpus/runner.js';

package/build/esm/routes/generated.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"generated.d.ts","sourceRoot":"","sources":["../../../src/routes/generated.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAA;AAEjD,eAAO,MAAM,gBAAgB,EAAE,cAAc,EA+jD5C,CAAA"}
+{"version":3,"file":"generated.d.ts","sourceRoot":"","sources":["../../../src/routes/generated.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAA;AAEjD,eAAO,MAAM,gBAAgB,EAAE,cAAc,EA6oD5C,CAAA"}