@andco/sdk 0.0.2 → 0.0.4

package/dist/service.js

@@ -0,0 +1,241 @@
+import { ANDCO_API_ORIGIN, assertAndCoResource, parseServiceGrants, parseServiceSubject, parseServiceToken, } from "@andco/protocol";
+import { AndcoConfig } from "./config.js";
+import { ANDCO_REFRESH_SKEW_SECONDS } from "./credentials.js";
+import { AndcoError } from "./errors.js";
+import { resolveGlobals } from "./globals.js";
+import { grantId } from "./grants.js";
+import { AndcoIntents } from "./intents.js";
+import { AndcoRest } from "./rest.js";
+/** No approved Grant covers this subject and resource. Version one never opens a login flow. */
+export class AndcoAuthorizationRequiredError extends AndcoError {
+    subject;
+    resource;
+    constructor(subject, resource) {
+        super("authorization_required", {
+            message: "No approved Grant covers this subject and resource; approve one in Platform",
+            details: { subject, resource },
+        });
+        this.subject = subject;
+        this.resource = resource;
+    }
+}
+/**
+ * Confidential client acting for Organizations through Grants approved in Platform.
+ *
+ * Each call sends the subject and the resource, and the Authorization Server selects the Grant.
+ * When more than one Grant qualifies the exchange fails with `ambiguous_grant`, whose `details`
+ * name the candidate ids; pass one as `grant` to pin it. Access tokens live in memory only.
+ *
+ * @example
+ * ```ts
+ * const service = createAndcoService({ clientId, clientSecret });
+ * const bank = new Bank(service.credentials({ subject: { type: "organization", identifier: "123" } }));
+ * const { data } = await bank.client.http.GET("/accounts").throwOnError();
+ * await service.intents({ subject: { type: "organization", identifier: "123" } }).approve(transferId);
+ * ```
+ */
+export class AndcoService {
+    config;
+    rest;
+    #subject;
+    #resource;
+    #secret;
+    #globals;
+    #tokens = new Map();
+    #pending = new Map();
+    constructor(options) {
+        if (typeof window !== "undefined")
+            throw new AndcoError("browser_forbidden", { message: "Service credentials cannot be used in a browser" });
+        if (typeof options.clientSecret !== "string" || !options.clientSecret)
+            throw new AndcoError("invalid_configuration", { message: "Service requires clientSecret" });
+        this.config = AndcoConfig.from(options);
+        this.#subject = options.subject === undefined ? undefined : parseSubject(options.subject);
+        this.#resource = options.resource ?? ANDCO_API_ORIGIN;
+        assertAndCoResource(this.#resource);
+        this.#secret = options.clientSecret;
+        this.#globals = resolveGlobals(options.globals);
+        this.rest = new AndcoRest({
+            config: this.config,
+            globals: this.#globals,
+            credentials: this.credentials(),
+            resource: this.#resource,
+        });
+    }
+    /**
+     * Credentials for Bank or another Resource Server definition, acting for one Organization.
+     *
+     * @example
+     * ```ts
+     * const bank = new Bank(service.credentials({ subject: { type: "organization", identifier: "123" } }));
+     * ```
+     */
+    credentials(options = {}) {
+        const subject = options.subject === undefined ? this.#subject : parseSubject(options.subject);
+        const grant = options.grant === undefined ? undefined : grantId(options.grant);
+        return this.#credentials(subject, grant);
+    }
+    /**
+     * The Intent lifecycle (`approve`, `reject`, `cancel`, `get`, `events`, `subscribe`) acting for
+     * one Organization: the same {@link AndcoIntents} `andco.intents` exposes, authorized with
+     * `credentials(options)`. A method rather than a property, like `credentials()`, because the
+     * subject and the Grant are chosen per call; without options it acts for the Service's `subject`.
+     * Presentation needs a person and a browser, so `present()` and `presentationURL()` are not for a
+     * Service.
+     *
+     * @example
+     * ```ts
+     * const intents = service.intents({ subject: { type: "organization", identifier: "123" } });
+     * await intents.approve(transferId); // the server selects the Grant holding bank_transfer approve
+     * await service.intents({ grant: approverGrantId }).reject(transferId, { reason: "over_budget" });
+     * const { data: transfer } = await service.intents().get(transferId);
+     * ```
+     */
+    intents(options = {}) {
+        console.debug("[AndcoService.intents] binding Intents for %o grant %s", options.subject ?? this.#subject, options.grant === undefined ? "(server)" : grantId(options.grant));
+        const rest = new AndcoRest({
+            config: this.config,
+            globals: this.#globals,
+            credentials: this.credentials(options),
+            resource: this.#resource,
+        });
+        return new AndcoIntents({ rest, config: this.config, globals: this.#globals });
+    }
+    /**
+     * Lists the active Grants the server would select from for one subject and resource.
+     *
+     * @example
+     * ```ts
+     * const grants = await service.listGrants({ subject: { type: "organization", identifier: "123" } });
+     * const bank = new Bank(service.credentials({ subject, grant: grants[0] }));
+     * ```
+     */
+    async listGrants(options = {}) {
+        const subject = this.#require(options.subject === undefined ? this.#subject : parseSubject(options.subject));
+        const resource = options.resource ?? this.#resource;
+        assertAndCoResource(resource);
+        const grants = parseServiceGrants(await this.#exchange("oauth/grants", parameters(subject, resource)));
+        console.debug("[AndcoService.listGrants] %s Grants for %o on %s", grants.length, subject, resource);
+        return grants;
+    }
+    #credentials(subject, fixed, pin) {
+        const credentials = {
+            config: this.config,
+            forOperation: () => this.#credentials(subject, fixed, {}),
+            accessTokenFor: async (resource, request) => {
+                assertAndCoResource(resource);
+                const target = this.#require(subject);
+                const explicit = request?.grant === undefined ? fixed : grantId(request.grant);
+                if (pin?.grant && explicit !== undefined && explicit !== pin.grant)
+                    throw new AndcoError("invalid_grant", { message: "Operation authority is already pinned" });
+                const grant = explicit ?? pin?.grant;
+                const issued = await this.#token(target, resource, grant);
+                if (pin)
+                    pin.grant = issued.grantId;
+                return issued.token;
+            },
+        };
+        return credentials;
+    }
+    #require(subject) {
+        if (subject === undefined)
+            throw new AndcoError("invalid_configuration", {
+                message: "Service requires a subject: pass one to createAndcoService() or service.credentials()",
+            });
+        return subject;
+    }
+    async #token(subject, resource, grant) {
+        const now = Date.now() / 1000;
+        for (const [key, cached] of this.#tokens)
+            if (cached.expiresAt <= now + ANDCO_REFRESH_SKEW_SECONDS)
+                this.#tokens.delete(key);
+        const body = parameters(subject, resource);
+        body.set("grant_type", "client_credentials");
+        if (grant !== undefined)
+            body.set("grant_id", grant);
+        const key = body.toString();
+        const cached = this.#tokens.get(key);
+        if (cached)
+            return { token: cached.token, grantId: cached.grantId };
+        const pending = this.#pending.get(key);
+        if (pending)
+            return pending;
+        const acquire = (async () => {
+            console.debug("[AndcoService.token] exchanging for %o on %s grant %s", subject, resource, grant ?? "(server)");
+            let payload;
+            try {
+                payload = await this.#exchange("oauth/token", body);
+            }
+            catch (error) {
+                if (AndcoError.is(error) && error.code === "authorization_required")
+                    throw new AndcoAuthorizationRequiredError(subject, resource);
+                throw error;
+            }
+            const token = parseServiceToken(payload);
+            if (grant !== undefined && token.authorization_grant_id !== grant)
+                throw new AndcoError("invalid_response", { message: "Issuer substituted the explicit Grant" });
+            const issued = {
+                token: token.access_token,
+                expiresAt: Date.now() / 1000 + token.expires_in,
+                grantId: token.authorization_grant_id,
+            };
+            this.#tokens.set(key, issued);
+            // A server-selected token is also the token of its exact Grant, so a pinned operation reuses it.
+            const exact = new URLSearchParams(body);
+            exact.set("grant_id", token.authorization_grant_id);
+            this.#tokens.set(exact.toString(), issued);
+            console.debug("[AndcoService.token] issued with Grant %s", token.authorization_grant_id);
+            return { token: token.access_token, grantId: token.authorization_grant_id };
+        })();
+        this.#pending.set(key, acquire);
+        try {
+            return await acquire;
+        }
+        finally {
+            this.#pending.delete(key);
+        }
+    }
+    async #exchange(path, body) {
+        const basic = btoa(`${encodeURIComponent(this.config.clientId)}:${encodeURIComponent(this.#secret)}`);
+        const response = await this.#globals.fetch(this.config.authURL(path), {
+            method: "POST",
+            headers: { Authorization: `Basic ${basic}`, "Content-Type": "application/x-www-form-urlencoded" },
+            body,
+            redirect: "error",
+        });
+        const payload = await response.json().catch((cause) => {
+            throw new AndcoError("invalid_response", {
+                status: response.status,
+                cause,
+                message: "Issuer returned invalid JSON",
+            });
+        });
+        if (!response.ok) {
+            const { error, error_description, ...details } = payload && typeof payload === "object" ? payload : {};
+            console.debug("[AndcoService.exchange] %s failed %s %s", path, response.status, error);
+            throw new AndcoError(typeof error === "string" ? error : "invalid_response", {
+                status: response.status,
+                message: typeof error_description === "string" ? error_description : undefined,
+                details: Object.keys(details).length ? details : undefined,
+            });
+        }
+        return payload;
+    }
+}
+function parseSubject(subject) {
+    try {
+        return parseServiceSubject(subject);
+    }
+    catch (cause) {
+        throw new AndcoError("invalid_configuration", {
+            cause,
+            message: 'A Service subject is { type: "organization", identifier } with an exact Organization id',
+        });
+    }
+}
+function parameters(subject, resource) {
+    return new URLSearchParams({ subject: JSON.stringify(subject), resource });
+}
+/** Constructs a service lazily; does not perform network I/O or approve access. */
+export function createAndcoService(options) {
+    return new AndcoService(options);
+}

package/dist/session-store.d.ts

@@ -1,21 +1,24 @@
 import type { AndcoConfig } from "./config.js";
 import { type AndcoCredentials, type AndcoSession } from "./credentials.js";
 import { AndcoError, Result } from "./errors.js";
+import { type AndcoInflight } from "./inflight.js";
 import type { AndcoOAuth } from "./oauth.js";
-import { type AndcoLock, type AndcoStorage } from "./storage.js";
+import { type AndcoStorage } from "./storage.js";
 /** Reads a session that arrived from somewhere other than storage, such as a URL callback. */
 export type AndcoSessionSource = () => Promise<Result<AndcoSession | null>>;
+/** Lazy session loading, persistence, refresh, and initial hydration options. */
 export type AndcoSessionStoreOptions = {
     config: AndcoConfig;
     oauth: AndcoOAuth;
+    /** Persists serialized sessions. Defaults to memory for this store's lifetime. */
     storage?: AndcoStorage;
     /** A session the caller already resolved. Makes the first snapshot real instead of unresolved. */
     initialSession?: AndcoSession | null;
-    /** Serializes refresh beyond this runtime. Defaults to in-process only. */
-    lock?: AndcoLock;
+    /** Shares one refresh among concurrent callers. Defaults to this runtime only. */
+    inflight?: AndcoInflight;
     /** Consulted once during the load, before storage. Used for URL callbacks. */
     source?: AndcoSessionSource;
-    /** Whether a loaded session is written back to storage. */
+    /** Writes session changes to storage unless `false`; defaults to `true`. */
     persist?: boolean;
 };
 /**
@@ -71,6 +74,11 @@ export declare class AndcoSessionStore implements AndcoCredentials {
      * discarded instance be inert and removes any need for instance identity.
      */
     accessTokenFor(resource: string): Promise<string | null>;
+    /**
+     * Refreshes now, even if the session is still fresh. Concurrent calls, and concurrent token
+     * resolutions that find the session stale, share one token request.
+     */
+    refresh(): Promise<Result<AndcoSession>>;
     /**
      * Replaces the stored session. This is the supported way to restore a saved credential, which
      * previously required writing a JSON blob into the SDK's private storage key because no such

package/dist/session-store.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"session-store.d.ts","sourceRoot":"","sources":["../src/session-store.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC/C,OAAO,EAAE,KAAK,gBAAgB,EAAE,KAAK,YAAY,EAAuB,MAAM,kBAAkB,CAAC;AACjG,OAAO,EAAqB,UAAU,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AACpE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAC7C,OAAO,EAAE,KAAK,SAAS,EAAE,KAAK,YAAY,EAAgC,MAAM,cAAc,CAAC;AAE/F,8FAA8F;AAC9F,MAAM,MAAM,kBAAkB,GAAG,MAAM,OAAO,CAAC,MAAM,CAAC,YAAY,GAAG,IAAI,CAAC,CAAC,CAAC;AAE5E,MAAM,MAAM,wBAAwB,GAAG;IACrC,MAAM,EAAE,WAAW,CAAC;IACpB,KAAK,EAAE,UAAU,CAAC;IAClB,OAAO,CAAC,EAAE,YAAY,CAAC;IACvB,kGAAkG;IAClG,cAAc,CAAC,EAAE,YAAY,GAAG,IAAI,CAAC;IACrC,2EAA2E;IAC3E,IAAI,CAAC,EAAE,SAAS,CAAC;IACjB,8EAA8E;IAC9E,MAAM,CAAC,EAAE,kBAAkB,CAAC;IAC5B,2DAA2D;IAC3D,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,qBAAa,iBAAkB,YAAW,gBAAgB;;gBAWrC,OAAO,EAAE,wBAAwB;IASpD;;;;;;OAMG;IACI,WAAW,IAAI,YAAY,GAAG,IAAI,GAAG,SAAS;IAIrD,4FAA4F;IACrF,iBAAiB,IAAI,YAAY,GAAG,IAAI,GAAG,SAAS;IAI3D,sFAAsF;IAC/E,SAAS,CAAC,QAAQ,EAAE,MAAM,IAAI,GAAG,MAAM,IAAI;IAQlD;;;;;;OAMG;IACH,IAAW,KAAK,IAAI,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAExC;IAED;;;;;OAKG;IACU,cAAc,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;IAsBrE;;;;OAIG;IACU,GAAG,CAAC,OAAO,EAAE,YAAY,GAAG,IAAI,GAAG,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;CAsDtE;AAgBD,6EAA6E;AAC7E,wBAAgB,eAAe,IAAI,UAAU,CAE5C"}
+{"version":3,"file":"session-store.d.ts","sourceRoot":"","sources":["../src/session-store.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC/C,OAAO,EAAE,KAAK,gBAAgB,EAAE,KAAK,YAAY,EAAuB,MAAM,kBAAkB,CAAC;AACjG,OAAO,EAAqB,UAAU,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AACpE,OAAO,EAAE,KAAK,aAAa,EAAkB,MAAM,eAAe,CAAC;AACnE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAC7C,OAAO,EAAE,KAAK,YAAY,EAAiB,MAAM,cAAc,CAAC;AAEhE,8FAA8F;AAC9F,MAAM,MAAM,kBAAkB,GAAG,MAAM,OAAO,CAAC,MAAM,CAAC,YAAY,GAAG,IAAI,CAAC,CAAC,CAAC;AAE5E,iFAAiF;AACjF,MAAM,MAAM,wBAAwB,GAAG;IACrC,MAAM,EAAE,WAAW,CAAC;IACpB,KAAK,EAAE,UAAU,CAAC;IAClB,kFAAkF;IAClF,OAAO,CAAC,EAAE,YAAY,CAAC;IACvB,kGAAkG;IAClG,cAAc,CAAC,EAAE,YAAY,GAAG,IAAI,CAAC;IACrC,kFAAkF;IAClF,QAAQ,CAAC,EAAE,aAAa,CAAC;IACzB,8EAA8E;IAC9E,MAAM,CAAC,EAAE,kBAAkB,CAAC;IAC5B,4EAA4E;IAC5E,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,qBAAa,iBAAkB,YAAW,gBAAgB;;gBAWrC,OAAO,EAAE,wBAAwB;IASpD;;;;;;OAMG;IACI,WAAW,IAAI,YAAY,GAAG,IAAI,GAAG,SAAS;IAIrD,4FAA4F;IACrF,iBAAiB,IAAI,YAAY,GAAG,IAAI,GAAG,SAAS;IAI3D,sFAAsF;IAC/E,SAAS,CAAC,QAAQ,EAAE,MAAM,IAAI,GAAG,MAAM,IAAI;IAQlD;;;;;;OAMG;IACH,IAAW,KAAK,IAAI,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAExC;IAED;;;;;OAKG;IACU,cAAc,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;IAarE;;;OAGG;IACU,OAAO,IAAI,OAAO,CAAC,MAAM,CAAC,YAAY,CAAC,CAAC;IAuBrD;;;;OAIG;IACU,GAAG,CAAC,OAAO,EAAE,YAAY,GAAG,IAAI,GAAG,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;CAmFtE;AAgBD,6EAA6E;AAC7E,wBAAgB,eAAe,IAAI,UAAU,CAE5C"}

package/dist/session-store.js

@@ -1,6 +1,7 @@
 import { isExpired, tokenFor } from "./credentials.js";
 import { ANDCO_ERROR_CODES, AndcoError, Result } from "./errors.js";
-import { InProcessLock, MemoryStorage } from "./storage.js";
+import { MemoryInflight } from "./inflight.js";
+import { MemoryStorage } from "./storage.js";
 /**
  * The credential as a resource, and the only stateful object in the SDK.
  *
@@ -27,7 +28,7 @@ import { InProcessLock, MemoryStorage } from "./storage.js";
 export class AndcoSessionStore {
     #options;
     #storage;
-    #lock;
+    #inflight;
     #listeners = new Set();
     #key;
     #hydrated;
@@ -36,7 +37,7 @@ export class AndcoSessionStore {
     constructor(options) {
         this.#options = options;
         this.#storage = options.storage ?? new MemoryStorage();
-        this.#lock = options.lock ?? new InProcessLock();
+        this.#inflight = options.inflight ?? new MemoryInflight();
         this.#key = `andco.session.${options.config.clientId}`;
         this.#hydrated = options.initialSession;
         this.#snapshot = options.initialSession;
@@ -86,23 +87,42 @@ export class AndcoSessionStore {
             return null;
         if (!isExpired(current))
             return tokenFor(current, resource);
-        // Serialized per resource: refreshing one Resource Server's token must not block another's.
-        const refreshed = await this.#lock.acquire(`${this.#key}:${resource}`, async () => {
-            const latest = this.#snapshot;
+        // One refresh grant renews every resource, so concurrent callers share it whatever they asked for.
+        const refreshed = await this.#refresh(false);
+        if (refreshed.error)
+            return null;
+        return refreshed.data ? tokenFor(refreshed.data, resource) : null;
+    }
+    /**
+     * Refreshes now, even if the session is still fresh. Concurrent calls, and concurrent token
+     * resolutions that find the session stale, share one token request.
+     */
+    async refresh() {
+        await this.#ensureLoaded();
+        const refreshed = await this.#refresh(true);
+        if (refreshed.error)
+            return Result.fail(refreshed.error);
+        if (!refreshed.data)
+            return Result.fail(ANDCO_ERROR_CODES.SESSION_MISSING);
+        return Result.ok(refreshed.data);
+    }
+    async #refresh(force) {
+        console.debug("[refresh] requested force=%s", force);
+        return this.#inflight.run(this.#key, async () => {
+            const latest = await this.#latest();
             if (!latest)
-                return null;
-            // Another holder of the lock may have refreshed while this one waited.
-            if (!isExpired(latest))
-                return latest;
+                return Result.ok(null);
+            // Another caller, or another tab sharing the storage, may have refreshed already.
+            if (!force && !isExpired(latest))
+                return Result.ok(latest);
             if (!latest.refreshToken)
-                return null;
+                return Result.fail(ANDCO_ERROR_CODES.SESSION_MISSING);
             const result = await this.#options.oauth.refresh(latest.refreshToken);
             if (result.error)
-                return null;
+                return Result.fail(result.error);
             await this.#write(result.data);
-            return result.data;
+            return Result.ok(result.data);
         });
-        return refreshed ? tokenFor(refreshed, resource) : null;
     }
     /**
      * Replaces the stored session. This is the supported way to restore a saved credential, which
@@ -148,6 +168,36 @@ export class AndcoSessionStore {
             return Result.fail(AndcoError.from(cause, ANDCO_ERROR_CODES.STORAGE_FAILED));
         }
     }
+    /**
+     * The newest session between memory and storage.
+     *
+     * Storage shared by several runtimes — `localStorage` across tabs — may hold a session another
+     * runtime refreshed after this one loaded. Refresh tokens rotate, so refreshing with the copy in
+     * memory would present a token already replaced, which the Authorization Server tolerates only
+     * for a short interval and otherwise treats as reuse. Storage wins only when it is newer: a
+     * hydrated session is never written, so an empty storage does not mean signed out.
+     */
+    async #latest() {
+        const current = this.#snapshot ?? null;
+        if (this.#options.persist === false)
+            return current;
+        let persisted;
+        try {
+            const stored = await this.#storage.getItem(this.#key);
+            persisted = stored ? parseSession(stored) : null;
+        }
+        catch (cause) {
+            console.warn("[AndcoSessionStore] could not read storage before refreshing: %o", cause);
+            return current;
+        }
+        if (!persisted)
+            return current;
+        if (current && persisted.expiresAt <= current.expiresAt)
+            return current;
+        console.debug("[AndcoSessionStore] adopting a newer stored session expiring at %s", persisted.expiresAt);
+        this.#publish(persisted);
+        return persisted;
+    }
     async #write(session) {
         if (this.#options.persist !== false) {
             if (session)

package/dist/storage.d.ts

@@ -27,35 +27,28 @@ export declare class MemoryStorage implements AndcoStorage {
     setItem(key: string, value: string): void;
     removeItem(key: string): void;
 }
-/** Adapts a Web Storage object. Its synchronous methods satisfy the asynchronous-capable contract. */
-export declare class WebStorage implements AndcoStorage {
-    private readonly storage;
-    constructor(storage: Storage);
+/**
+ * Keeps a session in `window.localStorage`: shared by every tab of the origin and kept across browser
+ * restarts. The browser default.
+ *
+ * The global is read on each call, not at construction, so building one during a server render is
+ * safe; only using it there fails.
+ */
+export declare class LocalStorage implements AndcoStorage {
     getItem(key: string): string | null;
     setItem(key: string, value: string): void;
     removeItem(key: string): void;
 }
 /**
- * Serializes an operation per key.
- *
- * Refresh tokens rotate, so two concurrent refreshes destroy a session: the first rotates the token
- * and every other one fails against a token that no longer exists. In-process single-flight covers
- * one runtime; this covers several, which is what a serverless deployment and multiple browser tabs
- * need. Not offering it is why both example backends invented their own locking, differently.
+ * Keeps a session in `window.sessionStorage`: one tab only, gone when the tab closes. A new tab starts
+ * signed out.
  *
- * @example
- * ```ts
- * const lock: AndcoLock = {
- *   acquire: (key, operation) => redlock.using([`andco:${key}`], 5000, operation),
- * };
- * ```
+ * The global is read on each call, not at construction, so building one during a server render is
+ * safe; only using it there fails.
  */
-export interface AndcoLock {
-    acquire<T>(key: string, operation: () => Promise<T>): Promise<T>;
-}
-/** Serializes per key within one runtime. The default, and enough for a single process. */
-export declare class InProcessLock implements AndcoLock {
-    #private;
-    acquire<T>(key: string, operation: () => Promise<T>): Promise<T>;
+export declare class SessionStorage implements AndcoStorage {
+    getItem(key: string): string | null;
+    setItem(key: string, value: string): void;
+    removeItem(key: string): void;
 }
 //# sourceMappingURL=storage.d.ts.map

package/dist/storage.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"storage.d.ts","sourceRoot":"","sources":["../src/storage.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,WAAW,YAAY;IAC3B,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IAC7D,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC1D,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC/C;AAED,2FAA2F;AAC3F,qBAAa,aAAc,YAAW,YAAY;;IAGzC,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI;IAInC,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI;IAIzC,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;CAGrC;AAED,sGAAsG;AACtG,qBAAa,UAAW,YAAW,YAAY;IAC1B,OAAO,CAAC,QAAQ,CAAC,OAAO;gBAAP,OAAO,EAAE,OAAO;IAE7C,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI;IAInC,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI;IAIzC,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;CAGrC;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,WAAW,SAAS;IACxB,OAAO,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;CAClE;AAED,2FAA2F;AAC3F,qBAAa,aAAc,YAAW,SAAS;;IAGhC,OAAO,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;CAe9E"}
+{"version":3,"file":"storage.d.ts","sourceRoot":"","sources":["../src/storage.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,WAAW,YAAY;IAC3B,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IAC7D,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC1D,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC/C;AAED,2FAA2F;AAC3F,qBAAa,aAAc,YAAW,YAAY;;IAGzC,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI;IAInC,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI;IAIzC,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;CAGrC;AAED;;;;;;GAMG;AACH,qBAAa,YAAa,YAAW,YAAY;IACxC,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI;IAInC,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI;IAIzC,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;CAGrC;AAED;;;;;;GAMG;AACH,qBAAa,cAAe,YAAW,YAAY;IAC1C,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI;IAInC,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI;IAIzC,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;CAGrC"}

package/dist/storage.js

@@ -11,37 +11,39 @@ export class MemoryStorage {
         this.#values.delete(key);
     }
 }
-/** Adapts a Web Storage object. Its synchronous methods satisfy the asynchronous-capable contract. */
-export class WebStorage {
-    storage;
-    constructor(storage) {
-        this.storage = storage;
-    }
+/**
+ * Keeps a session in `window.localStorage`: shared by every tab of the origin and kept across browser
+ * restarts. The browser default.
+ *
+ * The global is read on each call, not at construction, so building one during a server render is
+ * safe; only using it there fails.
+ */
+export class LocalStorage {
     getItem(key) {
-        return this.storage.getItem(key);
+        return window.localStorage.getItem(key);
     }
     setItem(key, value) {
-        this.storage.setItem(key, value);
+        window.localStorage.setItem(key, value);
     }
     removeItem(key) {
-        this.storage.removeItem(key);
+        window.localStorage.removeItem(key);
     }
 }
-/** Serializes per key within one runtime. The default, and enough for a single process. */
-export class InProcessLock {
-    #queues = new Map();
-    async acquire(key, operation) {
-        const previous = this.#queues.get(key) ?? Promise.resolve();
-        const run = previous.then(operation, operation);
-        // The stored link never rejects, so one failed operation cannot wedge the key for the next.
-        const link = run.then(() => undefined, () => undefined);
-        this.#queues.set(key, link);
-        try {
-            return await run;
-        }
-        finally {
-            if (this.#queues.get(key) === link)
-                this.#queues.delete(key);
-        }
+/**
+ * Keeps a session in `window.sessionStorage`: one tab only, gone when the tab closes. A new tab starts
+ * signed out.
+ *
+ * The global is read on each call, not at construction, so building one during a server render is
+ * safe; only using it there fails.
+ */
+export class SessionStorage {
+    getItem(key) {
+        return window.sessionStorage.getItem(key);
+    }
+    setItem(key, value) {
+        window.sessionStorage.setItem(key, value);
+    }
+    removeItem(key) {
+        window.sessionStorage.removeItem(key);
     }
 }

package/dist/tokens.d.ts

@@ -0,0 +1,46 @@
+import type { AndcoConfig } from "./config.js";
+import { Result } from "./errors.js";
+import type { AndcoGlobals } from "./globals.js";
+/** Registered claims of an Andco access token, plus whatever else the Authorization Server signed. */
+export type AndcoTokenClaims = {
+    readonly iss: string;
+    readonly sub?: string;
+    readonly aud?: string | readonly string[];
+    readonly exp: number;
+    readonly iat?: number;
+    readonly scope?: string;
+    readonly client_id?: string;
+} & Readonly<Record<string, unknown>>;
+/** Constraints beyond signature, `exp` and `iss`, which are always checked. */
+export type AndcoTokenVerifyOptions = {
+    /** Resource Indicator the token must be addressed to. Omit to accept any audience. */
+    audience?: string;
+    /** Accepted clock drift in seconds. Defaults to 30. */
+    clockToleranceSeconds?: number;
+};
+/**
+ * Offline verification of Andco access tokens with the Authorization Server's JWKS.
+ *
+ * The JWKS URL comes from the baked Server Description, re-rooted on the configured issuer, and
+ * keys are cached by `kid`. An unknown `kid` triggers one (rate limited) refetch, which is how a key
+ * rotation is picked up without a restart. A valid signature proves who issued the token, not that
+ * the Grant behind it is still alive: use `grants.get` for that.
+ *
+ * @example
+ * ```ts
+ * const { data: claims, error } = await andco.tokens.verify(bearer, { audience: "https://api.casa-norte.example" });
+ * if (error) return new Response(null, { status: 401 });
+ * ```
+ */
+export declare class AndcoTokens {
+    #private;
+    constructor(options: {
+        config: AndcoConfig;
+        globals: AndcoGlobals;
+    });
+    /** The `iss` the Authorization Server signs: the configured base URL without a trailing slash. */
+    get issuer(): string;
+    /** Checks signature, `exp`, `iss` and, when given, `aud`. Never throws. */
+    verify(token: string, options?: AndcoTokenVerifyOptions): Promise<Result<AndcoTokenClaims>>;
+}
+//# sourceMappingURL=tokens.d.ts.map

package/dist/tokens.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tokens.d.ts","sourceRoot":"","sources":["../src/tokens.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC/C,OAAO,EAAc,MAAM,EAAE,MAAM,aAAa,CAAC;AACjD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAGjD,sGAAsG;AACtG,MAAM,MAAM,gBAAgB,GAAG;IAC7B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,SAAS,MAAM,EAAE,CAAC;IAC1C,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;CAC7B,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;AAEtC,+EAA+E;AAC/E,MAAM,MAAM,uBAAuB,GAAG;IACpC,sFAAsF;IACtF,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,uDAAuD;IACvD,qBAAqB,CAAC,EAAE,MAAM,CAAC;CAChC,CAAC;AAmBF;;;;;;;;;;;;;GAaG;AACH,qBAAa,WAAW;;gBAOH,OAAO,EAAE;QAAE,MAAM,EAAE,WAAW,CAAC;QAAC,OAAO,EAAE,YAAY,CAAA;KAAE;IAK1E,kGAAkG;IAClG,IAAW,MAAM,IAAI,MAAM,CAG1B;IAED,2EAA2E;IAC9D,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,GAAE,uBAA4B,GAAG,OAAO,CAAC,MAAM,CAAC,gBAAgB,CAAC,CAAC;CAgF7G"}