@soulcode/bexio-oauth 0.0.0-stage → 0.2.0

package/dist/crypto.js

@@ -0,0 +1,106 @@
+import { createHash, hkdfSync, randomBytes } from "node:crypto";
+import { CompactEncrypt, compactDecrypt, EncryptJWT, jwtDecrypt } from "jose";
+import { BexioOAuthError } from "./errors.js";
+const JWE_ALGORITHMS = {
+    keyManagementAlgorithms: ["dir"],
+    contentEncryptionAlgorithms: ["A256GCM"],
+};
+/** 32 bytes as unpadded base64url: exactly 43 characters of the base64url alphabet. */
+const KEY_FORMAT = /^[A-Za-z0-9_-]{43}$/;
+/** A new random key for the keyring, base64url-encoded. */
+export function generateKey() {
+    return randomBytes(32).toString("base64url");
+}
+function hash(value) {
+    return createHash("sha256").update(value).digest("base64url");
+}
+/**
+ * Encrypts tokens at rest as compact JWE (`dir` + `A256GCM`) and seals the
+ * short-lived flow cookie. The `bxg` protected header binds a token to the
+ * grant it belongs to, so ciphertext copied to another row fails to decrypt.
+ */
+export class TokenCipher {
+    #current;
+    #keys;
+    #flowKeys = new Map();
+    constructor(keyring) {
+        if (!keyring || typeof keyring !== "object" || !keyring.keys) {
+            throw new BexioOAuthError("invalid_config", "keys must be { current, keys }");
+        }
+        this.#keys = new Map();
+        for (const [kid, encoded] of Object.entries(keyring.keys)) {
+            // Strict: Buffer.from(…, "base64url") silently drops characters it
+            // doesn't know, so a mangled key could still "decode" to 32 bytes and
+            // then differ between environments.
+            if (typeof encoded !== "string" || !KEY_FORMAT.test(encoded)) {
+                throw new BexioOAuthError("invalid_config", `key "${kid}" must be 32 bytes, base64url-encoded without padding (43 characters)`);
+            }
+            this.#keys.set(kid, new Uint8Array(Buffer.from(encoded, "base64url")));
+        }
+        if (!this.#keys.has(keyring.current)) {
+            throw new BexioOAuthError("invalid_config", `keys.current "${keyring.current}" is not in keys`);
+        }
+        this.#current = keyring.current;
+    }
+    async encrypt(plaintext, binding) {
+        return new CompactEncrypt(new TextEncoder().encode(plaintext))
+            .setProtectedHeader({
+            alg: "dir",
+            enc: "A256GCM",
+            kid: this.#current,
+            bxg: hash(binding),
+        })
+            .encrypt(this.#key(this.#current).key);
+    }
+    async decrypt(jwe, binding) {
+        try {
+            const { plaintext, protectedHeader } = await compactDecrypt(jwe, (header) => this.#key(header.kid).key, JWE_ALGORITHMS);
+            if (protectedHeader.bxg !== hash(binding)) {
+                throw new Error("binding mismatch");
+            }
+            return new TextDecoder().decode(plaintext);
+        }
+        catch {
+            throw new BexioOAuthError("decryption_failed", "stored token could not be decrypted (unknown key id, or it belongs to another grant)");
+        }
+    }
+    async seal(payload, ttlSeconds, now) {
+        const nowSeconds = Math.floor(now.getTime() / 1000);
+        return new EncryptJWT(payload)
+            .setProtectedHeader({ alg: "dir", enc: "A256GCM", kid: this.#current })
+            .setIssuedAt(nowSeconds)
+            .setExpirationTime(nowSeconds + ttlSeconds)
+            .encrypt(this.#flowKey(this.#current));
+    }
+    /** Returns the payload, or `null` when the value is invalid or expired. */
+    async unseal(token, now) {
+        try {
+            const { payload } = await jwtDecrypt(token, (header) => this.#flowKey(header.kid), {
+                ...JWE_ALGORITHMS,
+                currentDate: now,
+            });
+            return payload;
+        }
+        catch {
+            return null;
+        }
+    }
+    /** The key for `kid`, with `kid` narrowed to a known key id. */
+    #key(kid) {
+        const key = kid === undefined ? undefined : this.#keys.get(kid);
+        if (kid === undefined || !key)
+            throw new Error("unknown key id");
+        return { kid, key };
+    }
+    // The flow cookie uses a key derived from the keyring, never the token key itself.
+    #flowKey(requested) {
+        const { kid, key: base } = this.#key(requested);
+        let derived = this.#flowKeys.get(kid);
+        if (!derived) {
+            derived = new Uint8Array(hkdfSync("sha256", base, new Uint8Array(0), "bexio-oauth/flow-cookie", 32));
+            this.#flowKeys.set(kid, derived);
+        }
+        return derived;
+    }
+}
+//# sourceMappingURL=crypto.js.map

package/dist/crypto.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"crypto.js","sourceRoot":"","sources":["../src/crypto.ts"],"names":[],"mappings":"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"}

package/dist/duration.d.ts

@@ -0,0 +1,4 @@
+/** Milliseconds, or a string like `"30s"`, `"15m"`, `"12h"`, `"7d"`. */
+export type Duration = number | `${number}${"s" | "m" | "h" | "d"}`;
+export declare function toMs(value: Duration, name: string): number;
+//# sourceMappingURL=duration.d.ts.map

package/dist/duration.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"duration.d.ts","sourceRoot":"","sources":["../src/duration.ts"],"names":[],"mappings":"AAEA,wEAAwE;AACxE,MAAM,MAAM,QAAQ,GAAG,MAAM,GAAG,GAAG,MAAM,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,EAAE,CAAC;AAIpE,wBAAgB,IAAI,CAAC,KAAK,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAY1D"}

package/dist/duration.js

@@ -0,0 +1,15 @@
+import { BexioOAuthError } from "./errors.js";
+const UNIT_MS = { s: 1_000, m: 60_000, h: 3_600_000, d: 86_400_000 };
+export function toMs(value, name) {
+    if (typeof value === "number") {
+        if (Number.isFinite(value) && value > 0)
+            return value;
+    }
+    else {
+        const match = /^(\d+(?:\.\d+)?)([smhd])$/.exec(value);
+        if (match)
+            return Number(match[1]) * UNIT_MS[match[2]];
+    }
+    throw new BexioOAuthError("invalid_config", `${name} must be a positive number of milliseconds or a string like "7d"`);
+}
+//# sourceMappingURL=duration.js.map

package/dist/duration.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"duration.js","sourceRoot":"","sources":["../src/duration.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAK9C,MAAM,OAAO,GAAG,EAAE,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,SAAS,EAAE,CAAC,EAAE,UAAU,EAAW,CAAC;AAE9E,MAAM,UAAU,IAAI,CAAC,KAAe,EAAE,IAAY;IAChD,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAC9B,IAAI,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,KAAK,GAAG,CAAC;YAAE,OAAO,KAAK,CAAC;IACxD,CAAC;SAAM,CAAC;QACN,MAAM,KAAK,GAAG,2BAA2B,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QACtD,IAAI,KAAK;YACP,OAAO,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC,CAAyB,CAAC,CAAC;IACxE,CAAC;IACD,MAAM,IAAI,eAAe,CACvB,gBAAgB,EAChB,GAAG,IAAI,kEAAkE,CAC1E,CAAC;AACJ,CAAC"}

package/dist/errors.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Every failure the library reports is a `BexioOAuthError` with a stable
+ * `code`. Messages never contain token values; `cause`, when set, is a safe
+ * summary of the upstream error (name, OAuth error code, HTTP status).
+ */
+export type BexioOAuthErrorCode = 
+/** Flow cookie missing, expired, or `state` does not match. */
+"state_mismatch"
+/** The `ownerId` at callback differs from the one passed to `start`. */
+ | "owner_mismatch"
+/** The user cancelled at Bexio. */
+ | "access_denied"
+/** Bad code, nonce or token signature, wrong issuer, or missing claims. */
+ | "invalid_callback"
+/** Bexio returned an unexpected error or was unreachable. */
+ | "idp_error"
+/** The owner has no grant (for that company / grant id). */
+ | "not_connected"
+/** The owner has several grants; pass `companyId` or `grantId`. */
+ | "ambiguous_grant"
+/** The refresh token is dead; the user has to reconnect. */
+ | "reauth_required"
+/** A stored token can't be decrypted (unknown key id, or it belongs to another grant). */
+ | "decryption_failed"
+/** The library was configured incorrectly. */
+ | "invalid_config";
+export declare class BexioOAuthError extends Error {
+    readonly code: BexioOAuthErrorCode;
+    constructor(code: BexioOAuthErrorCode, message: string, options?: {
+        cause?: {
+            name: string;
+            error?: string;
+            status?: number;
+        };
+    });
+}
+export declare function isBexioOAuthError(value: unknown, code?: BexioOAuthErrorCode): value is BexioOAuthError;
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,MAAM,MAAM,mBAAmB;AAC7B,+DAA+D;AAC7D,gBAAgB;AAClB,wEAAwE;GACtE,gBAAgB;AAClB,mCAAmC;GACjC,eAAe;AACjB,2EAA2E;GACzE,kBAAkB;AACpB,6DAA6D;GAC3D,WAAW;AACb,4DAA4D;GAC1D,eAAe;AACjB,mEAAmE;GACjE,iBAAiB;AACnB,4DAA4D;GAC1D,iBAAiB;AACnB,0FAA0F;GACxF,mBAAmB;AACrB,8CAA8C;GAC5C,gBAAgB,CAAC;AAErB,qBAAa,eAAgB,SAAQ,KAAK;IACxC,QAAQ,CAAC,IAAI,EAAE,mBAAmB,CAAC;gBAGjC,IAAI,EAAE,mBAAmB,EACzB,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE;YAAE,IAAI,EAAE,MAAM,CAAC;YAAC,KAAK,CAAC,EAAE,MAAM,CAAC;YAAC,MAAM,CAAC,EAAE,MAAM,CAAA;SAAE,CAAA;KAAE;CAM1E;AAED,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,OAAO,EACd,IAAI,CAAC,EAAE,mBAAmB,GACzB,KAAK,IAAI,eAAe,CAK1B"}

package/dist/errors.js

@@ -0,0 +1,13 @@
+export class BexioOAuthError extends Error {
+    code;
+    constructor(code, message, options) {
+        super(message, options);
+        this.name = "BexioOAuthError";
+        this.code = code;
+    }
+}
+export function isBexioOAuthError(value, code) {
+    return (value instanceof BexioOAuthError &&
+        (code === undefined || value.code === code));
+}
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AA2BA,MAAM,OAAO,eAAgB,SAAQ,KAAK;IAC/B,IAAI,CAAsB;IAEnC,YACE,IAAyB,EACzB,OAAe,EACf,OAAuE;QAEvE,KAAK,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;QACxB,IAAI,CAAC,IAAI,GAAG,iBAAiB,CAAC;QAC9B,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;IACnB,CAAC;CACF;AAED,MAAM,UAAU,iBAAiB,CAC/B,KAAc,EACd,IAA0B;IAE1B,OAAO,CACL,KAAK,YAAY,eAAe;QAChC,CAAC,IAAI,KAAK,SAAS,IAAI,KAAK,CAAC,IAAI,KAAK,IAAI,CAAC,CAC5C,CAAC;AACJ,CAAC"}

package/dist/external-tokens.d.ts

@@ -0,0 +1,8 @@
+import type { ClientContext } from "./config.js";
+import type { ExternalTokens, Grant } from "./types.js";
+/** `BexioOAuth.saveGrant`: verifies tokens from your auth framework, then stores them. */
+export declare function saveGrant(ctx: ClientContext, input: {
+    ownerId: string;
+    tokens: ExternalTokens;
+}): Promise<Grant>;
+//# sourceMappingURL=external-tokens.d.ts.map

package/dist/external-tokens.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"external-tokens.d.ts","sourceRoot":"","sources":["../src/external-tokens.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAIjD,OAAO,KAAK,EAAE,cAAc,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AA+CxD,0FAA0F;AAC1F,wBAAsB,SAAS,CAC7B,GAAG,EAAE,aAAa,EAClB,KAAK,EAAE;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,cAAc,CAAA;CAAE,GACjD,OAAO,CAAC,KAAK,CAAC,CAuDhB"}

package/dist/external-tokens.js

@@ -0,0 +1,73 @@
+import { errors as joseErrors, jwtVerify } from "jose";
+import { BexioOAuthError } from "./errors.js";
+import { saveTokens, toGrant, withUserInfo } from "./grants.js";
+import { describe } from "./oidc.js";
+const SIGNING_ALGORITHMS = ["RS256", "PS256", "ES256"];
+/**
+ * Verifies a token's signature against Bexio's keys, plus issuer, expiry and
+ * (when given) audience. Not getting the keys is `idp_error`; a token that
+ * fails a check is `invalid_callback`.
+ */
+async function verifyBexioJwt(ctx, token, issuer, audience) {
+    const keys = await ctx.oidc.keySet();
+    try {
+        const { payload } = await jwtVerify(token, keys, {
+            issuer,
+            audience,
+            algorithms: SIGNING_ALGORITHMS,
+            currentDate: ctx.clock(),
+        });
+        return payload;
+    }
+    catch (error) {
+        // Not getting Bexio's keys is an outage, not a bad token.
+        // (jose reports a bad JWKS response, e.g. a 503, as its generic error.)
+        if (error instanceof joseErrors.JWKSTimeout ||
+            error instanceof TypeError ||
+            (error instanceof joseErrors.JOSEError &&
+                error.code === "ERR_JOSE_GENERIC")) {
+            throw new BexioOAuthError("idp_error", "could not load Bexio's signing keys", { cause: describe(error) });
+        }
+        throw new BexioOAuthError("invalid_callback", "token signature, issuer or expiry check failed", { cause: describe(error) });
+    }
+}
+/** `BexioOAuth.saveGrant`: verifies tokens from your auth framework, then stores them. */
+export async function saveGrant(ctx, input) {
+    if (!input?.ownerId)
+        throw new BexioOAuthError("invalid_config", "ownerId is required");
+    const { tokens } = input;
+    if (!tokens?.accessToken)
+        throw new BexioOAuthError("invalid_config", "tokens.accessToken is required");
+    const issuer = (await ctx.oidc.config()).serverMetadata().issuer;
+    const accessClaims = await verifyBexioJwt(ctx, tokens.accessToken, issuer);
+    // Must be an access token issued to this app: rejects tokens issued to
+    // another client (token substitution) and ID tokens passed as access tokens.
+    if (accessClaims.azp !== ctx.clientId) {
+        throw new BexioOAuthError("invalid_callback", "access token was not issued to this client");
+    }
+    if (accessClaims.typ !== undefined && accessClaims.typ !== "Bearer") {
+        throw new BexioOAuthError("invalid_callback", "tokens.accessToken is not an access token");
+    }
+    const idClaims = tokens.idToken
+        ? await verifyBexioJwt(ctx, tokens.idToken, issuer, ctx.clientId)
+        : {};
+    if (tokens.idToken && idClaims.sub !== accessClaims.sub) {
+        throw new BexioOAuthError("invalid_callback", "ID token and access token belong to different users");
+    }
+    const claims = await withUserInfo(ctx, { ...accessClaims, ...idClaims }, tokens.accessToken);
+    const exp = typeof accessClaims.exp === "number"
+        ? new Date(accessClaims.exp * 1000)
+        : null;
+    const record = await saveTokens(ctx, {
+        ownerId: input.ownerId,
+        claims,
+        accessToken: tokens.accessToken,
+        refreshToken: tokens.refreshToken ?? null,
+        accessExpiresAt: tokens.expiresAt ?? exp,
+        refreshExpiresAt: null,
+        scope: tokens.scope ??
+            (typeof accessClaims.scope === "string" ? accessClaims.scope : null),
+    });
+    return toGrant(record);
+}
+//# sourceMappingURL=external-tokens.js.map

package/dist/external-tokens.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"external-tokens.js","sourceRoot":"","sources":["../src/external-tokens.ts"],"names":[],"mappings":"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"}

package/dist/flow-cookie.d.ts

@@ -0,0 +1,23 @@
+import type { JWTPayload } from "jose";
+import type { TokenCipher } from "./crypto.js";
+/** The encrypted, short-lived cookie that carries the Connect flow's state. */
+export declare const FLOW_COOKIE = "bexio_oauth_flow";
+export declare const FLOW_TTL_SECONDS = 600;
+export interface FlowState extends JWTPayload {
+    /** state */ s: string;
+    /** PKCE verifier */ v: string;
+    /** nonce */ n: string;
+    /** ownerId */ o: string;
+    /** returnTo */ r: string;
+}
+/** The value of cookie `name` in the request's `Cookie` header, or `null`. */
+export declare function readCookie(request: Request, name: string): string | null;
+/**
+ * The `Set-Cookie` value for the flow cookie, scoped to the callback path.
+ * `Secure` whenever the redirect URI is https. `("", 0)` deletes it.
+ */
+export declare function flowCookie(redirectUri: URL, value: string, maxAge: number): string;
+export declare function sealFlow(cipher: TokenCipher, flow: FlowState, now: Date): Promise<string>;
+/** The request's flow state, or `null` when the cookie is missing, invalid or expired. */
+export declare function readFlow(cipher: TokenCipher, request: Request, now: Date): Promise<FlowState | null>;
+//# sourceMappingURL=flow-cookie.d.ts.map

package/dist/flow-cookie.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"flow-cookie.d.ts","sourceRoot":"","sources":["../src/flow-cookie.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,MAAM,CAAC;AACvC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAE/C,+EAA+E;AAC/E,eAAO,MAAM,WAAW,qBAAqB,CAAC;AAC9C,eAAO,MAAM,gBAAgB,MAAM,CAAC;AAEpC,MAAM,WAAW,SAAU,SAAQ,UAAU;IAC3C,YAAY,CAAC,CAAC,EAAE,MAAM,CAAC;IACvB,oBAAoB,CAAC,CAAC,EAAE,MAAM,CAAC;IAC/B,YAAY,CAAC,CAAC,EAAE,MAAM,CAAC;IACvB,cAAc,CAAC,CAAC,EAAE,MAAM,CAAC;IACzB,eAAe,CAAC,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED,8EAA8E;AAC9E,wBAAgB,UAAU,CAAC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAUxE;AAED;;;GAGG;AACH,wBAAgB,UAAU,CACxB,WAAW,EAAE,GAAG,EAChB,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,MAAM,GACb,MAAM,CAUR;AAED,wBAAgB,QAAQ,CACtB,MAAM,EAAE,WAAW,EACnB,IAAI,EAAE,SAAS,EACf,GAAG,EAAE,IAAI,GACR,OAAO,CAAC,MAAM,CAAC,CAEjB;AAED,0FAA0F;AAC1F,wBAAsB,QAAQ,CAC5B,MAAM,EAAE,WAAW,EACnB,OAAO,EAAE,OAAO,EAChB,GAAG,EAAE,IAAI,GACR,OAAO,CAAC,SAAS,GAAG,IAAI,CAAC,CAI3B"}

package/dist/flow-cookie.js

@@ -0,0 +1,44 @@
+/** The encrypted, short-lived cookie that carries the Connect flow's state. */
+export const FLOW_COOKIE = "bexio_oauth_flow";
+export const FLOW_TTL_SECONDS = 600;
+/** The value of cookie `name` in the request's `Cookie` header, or `null`. */
+export function readCookie(request, name) {
+    const header = request.headers.get("cookie");
+    if (!header)
+        return null;
+    for (const part of header.split(";")) {
+        const index = part.indexOf("=");
+        if (index === -1)
+            continue;
+        if (part.slice(0, index).trim() === name)
+            return part.slice(index + 1).trim();
+    }
+    return null;
+}
+/**
+ * The `Set-Cookie` value for the flow cookie, scoped to the callback path.
+ * `Secure` whenever the redirect URI is https. `("", 0)` deletes it.
+ */
+export function flowCookie(redirectUri, value, maxAge) {
+    const parts = [
+        `${FLOW_COOKIE}=${value}`,
+        `Path=${redirectUri.pathname}`,
+        `Max-Age=${maxAge}`,
+        "HttpOnly",
+        "SameSite=Lax",
+    ];
+    if (redirectUri.protocol === "https:")
+        parts.push("Secure");
+    return parts.join("; ");
+}
+export function sealFlow(cipher, flow, now) {
+    return cipher.seal(flow, FLOW_TTL_SECONDS, now);
+}
+/** The request's flow state, or `null` when the cookie is missing, invalid or expired. */
+export async function readFlow(cipher, request, now) {
+    const sealed = readCookie(request, FLOW_COOKIE);
+    if (!sealed)
+        return null;
+    return (await cipher.unseal(sealed, now));
+}
+//# sourceMappingURL=flow-cookie.js.map

package/dist/flow-cookie.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"flow-cookie.js","sourceRoot":"","sources":["../src/flow-cookie.ts"],"names":[],"mappings":"AAGA,+EAA+E;AAC/E,MAAM,CAAC,MAAM,WAAW,GAAG,kBAAkB,CAAC;AAC9C,MAAM,CAAC,MAAM,gBAAgB,GAAG,GAAG,CAAC;AAUpC,8EAA8E;AAC9E,MAAM,UAAU,UAAU,CAAC,OAAgB,EAAE,IAAY;IACvD,MAAM,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;IAC7C,IAAI,CAAC,MAAM;QAAE,OAAO,IAAI,CAAC;IACzB,KAAK,MAAM,IAAI,IAAI,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE,CAAC;QACrC,MAAM,KAAK,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;QAChC,IAAI,KAAK,KAAK,CAAC,CAAC;YAAE,SAAS;QAC3B,IAAI,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC,IAAI,EAAE,KAAK,IAAI;YACtC,OAAO,IAAI,CAAC,KAAK,CAAC,KAAK,GAAG,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;IACxC,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,UAAU,CACxB,WAAgB,EAChB,KAAa,EACb,MAAc;IAEd,MAAM,KAAK,GAAG;QACZ,GAAG,WAAW,IAAI,KAAK,EAAE;QACzB,QAAQ,WAAW,CAAC,QAAQ,EAAE;QAC9B,WAAW,MAAM,EAAE;QACnB,UAAU;QACV,cAAc;KACf,CAAC;IACF,IAAI,WAAW,CAAC,QAAQ,KAAK,QAAQ;QAAE,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;IAC5D,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC1B,CAAC;AAED,MAAM,UAAU,QAAQ,CACtB,MAAmB,EACnB,IAAe,EACf,GAAS;IAET,OAAO,MAAM,CAAC,IAAI,CAAC,IAAI,EAAE,gBAAgB,EAAE,GAAG,CAAC,CAAC;AAClD,CAAC;AAED,0FAA0F;AAC1F,MAAM,CAAC,KAAK,UAAU,QAAQ,CAC5B,MAAmB,EACnB,OAAgB,EAChB,GAAS;IAET,MAAM,MAAM,GAAG,UAAU,CAAC,OAAO,EAAE,WAAW,CAAC,CAAC;IAChD,IAAI,CAAC,MAAM;QAAE,OAAO,IAAI,CAAC;IACzB,OAAO,CAAC,MAAM,MAAM,CAAC,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAqB,CAAC;AAChE,CAAC"}

package/dist/grants.d.ts

@@ -0,0 +1,36 @@
+import { type ClaimBag } from "./claims.js";
+import type { ClientContext } from "./config.js";
+import type { TokenCipher } from "./crypto.js";
+import type { GrantRecord, GrantStore } from "./store/types.js";
+import type { AccessToken, Grant, GrantSelector } from "./types.js";
+/** The app-facing view of a stored grant: no token material. */
+export declare function toGrant(r: GrantRecord): Grant;
+/** The binding a grant's ciphertexts are encrypted under. */
+export declare function bindingOf(record: GrantRecord): string;
+export declare function decryptFor(cipher: TokenCipher, record: GrantRecord, value: string): Promise<string>;
+/** Decrypts the grant's access token for the caller. */
+export declare function issue(cipher: TokenCipher, record: GrantRecord): Promise<AccessToken>;
+/** Exactly one grant of the owner, or `not_connected` / `ambiguous_grant`. */
+export declare function resolveGrant(store: GrantStore, selector: GrantSelector): Promise<GrantRecord>;
+/** The token's claims if it is a JWT, else none (Bexio access tokens usually are). */
+export declare function decodeIfJwt(token: string): ClaimBag;
+/**
+ * Adds userinfo claims, only when the tokens lack the company claims. Token
+ * claims win over userinfo; a userinfo failure keeps the token claims.
+ */
+export declare function withUserInfo(ctx: ClientContext, claims: ClaimBag, accessToken: string): Promise<ClaimBag>;
+/** Encrypts the tokens, reads the role and upserts the grant for the identity in `claims`. */
+export declare function saveTokens(ctx: ClientContext, input: {
+    ownerId: string;
+    claims: ClaimBag;
+    accessToken: string;
+    refreshToken: string | null;
+    accessExpiresAt: Date | null;
+    refreshExpiresAt: Date | null;
+    scope: string | null;
+}): Promise<GrantRecord>;
+export declare function listGrants(store: GrantStore, query: {
+    ownerId: string;
+}): Promise<Grant[]>;
+export declare function disconnect(ctx: ClientContext, selector: GrantSelector): Promise<void>;
+//# sourceMappingURL=grants.d.ts.map

package/dist/grants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"grants.d.ts","sourceRoot":"","sources":["../src/grants.ts"],"names":[],"mappings":"AAEA,OAAO,EAA2B,KAAK,QAAQ,EAAE,MAAM,aAAa,CAAC;AACrE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AACjD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAG/C,OAAO,KAAK,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAChE,OAAO,KAAK,EAAE,WAAW,EAAE,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAEpE,gEAAgE;AAChE,wBAAgB,OAAO,CAAC,CAAC,EAAE,WAAW,GAAG,KAAK,CAkB7C;AAED,6DAA6D;AAC7D,wBAAgB,SAAS,CAAC,MAAM,EAAE,WAAW,GAAG,MAAM,CAErD;AAED,wBAAgB,UAAU,CACxB,MAAM,EAAE,WAAW,EACnB,MAAM,EAAE,WAAW,EACnB,KAAK,EAAE,MAAM,GACZ,OAAO,CAAC,MAAM,CAAC,CAEjB;AAED,wDAAwD;AACxD,wBAAsB,KAAK,CACzB,MAAM,EAAE,WAAW,EACnB,MAAM,EAAE,WAAW,GAClB,OAAO,CAAC,WAAW,CAAC,CAMtB;AAED,8EAA8E;AAC9E,wBAAsB,YAAY,CAChC,KAAK,EAAE,UAAU,EACjB,QAAQ,EAAE,aAAa,GACtB,OAAO,CAAC,WAAW,CAAC,CAatB;AAED,sFAAsF;AACtF,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,QAAQ,CAMnD;AAED;;;GAGG;AACH,wBAAsB,YAAY,CAChC,GAAG,EAAE,aAAa,EAClB,MAAM,EAAE,QAAQ,EAChB,WAAW,EAAE,MAAM,GAClB,OAAO,CAAC,QAAQ,CAAC,CAYnB;AAED,8FAA8F;AAC9F,wBAAsB,UAAU,CAC9B,GAAG,EAAE,aAAa,EAClB,KAAK,EAAE;IACL,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,QAAQ,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,eAAe,EAAE,IAAI,GAAG,IAAI,CAAC;IAC7B,gBAAgB,EAAE,IAAI,GAAG,IAAI,CAAC;IAC9B,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;CACtB,GACA,OAAO,CAAC,WAAW,CAAC,CAuBtB;AAED,wBAAsB,UAAU,CAC9B,KAAK,EAAE,UAAU,EACjB,KAAK,EAAE;IAAE,OAAO,EAAE,MAAM,CAAA;CAAE,GACzB,OAAO,CAAC,KAAK,EAAE,CAAC,CAIlB;AAED,wBAAsB,UAAU,CAC9B,GAAG,EAAE,aAAa,EAClB,QAAQ,EAAE,aAAa,GACtB,OAAO,CAAC,IAAI,CAAC,CAef"}

package/dist/grants.js

@@ -0,0 +1,115 @@
+import * as oidc from "openid-client";
+import { decodeJwt } from "jose";
+import { grantBinding, mapClaims } from "./claims.js";
+import { BexioOAuthError } from "./errors.js";
+import { fetchRole } from "./permissions.js";
+/** The app-facing view of a stored grant: no token material. */
+export function toGrant(r) {
+    return {
+        id: r.id,
+        ownerId: r.ownerId,
+        companyId: r.companyId,
+        companyName: r.companyName,
+        userId: r.userId,
+        userName: r.userName,
+        userEmail: r.userEmail,
+        companyUserId: r.companyUserId,
+        role: r.role,
+        status: r.status,
+        scope: r.scope,
+        accessExpiresAt: r.accessExpiresAt,
+        lastRefreshedAt: r.lastRefreshedAt,
+        createdAt: r.createdAt,
+        updatedAt: r.updatedAt,
+    };
+}
+/** The binding a grant's ciphertexts are encrypted under. */
+export function bindingOf(record) {
+    return grantBinding(record.ownerId, record.companyId, record.userId);
+}
+export function decryptFor(cipher, record, value) {
+    return cipher.decrypt(value, bindingOf(record));
+}
+/** Decrypts the grant's access token for the caller. */
+export async function issue(cipher, record) {
+    return {
+        accessToken: await decryptFor(cipher, record, record.accessToken),
+        expiresAt: record.accessExpiresAt,
+        grant: toGrant(record),
+    };
+}
+/** Exactly one grant of the owner, or `not_connected` / `ambiguous_grant`. */
+export async function resolveGrant(store, selector) {
+    if (!selector?.ownerId)
+        throw new BexioOAuthError("invalid_config", "ownerId is required");
+    const rows = await store.findGrants(selector);
+    if (rows.length === 0)
+        throw new BexioOAuthError("not_connected", "owner has no matching grant");
+    if (rows.length > 1) {
+        throw new BexioOAuthError("ambiguous_grant", "owner has several grants; pass companyId or grantId");
+    }
+    return rows[0];
+}
+/** The token's claims if it is a JWT, else none (Bexio access tokens usually are). */
+export function decodeIfJwt(token) {
+    try {
+        return decodeJwt(token);
+    }
+    catch {
+        return {};
+    }
+}
+/**
+ * Adds userinfo claims, only when the tokens lack the company claims. Token
+ * claims win over userinfo; a userinfo failure keeps the token claims.
+ */
+export async function withUserInfo(ctx, claims, accessToken) {
+    if (claims.company_id !== undefined)
+        return claims;
+    try {
+        const info = await oidc.fetchUserInfo(await ctx.oidc.config(), accessToken, typeof claims.sub === "string" ? claims.sub : oidc.skipSubjectCheck);
+        return { ...info, ...claims };
+    }
+    catch {
+        return claims;
+    }
+}
+/** Encrypts the tokens, reads the role and upserts the grant for the identity in `claims`. */
+export async function saveTokens(ctx, input) {
+    const identity = mapClaims(input.claims);
+    const binding = grantBinding(input.ownerId, identity.companyId, identity.userId);
+    const role = (await fetchRole(ctx.fetchImpl, ctx.apiBaseUrl, input.accessToken)) ??
+        "member";
+    return ctx.store.upsertGrant({
+        ownerId: input.ownerId,
+        ...identity,
+        role,
+        accessToken: await ctx.cipher.encrypt(input.accessToken, binding),
+        refreshToken: input.refreshToken
+            ? await ctx.cipher.encrypt(input.refreshToken, binding)
+            : null,
+        accessExpiresAt: input.accessExpiresAt,
+        refreshExpiresAt: input.refreshExpiresAt,
+        scope: input.scope,
+        now: ctx.clock(),
+    });
+}
+export async function listGrants(store, query) {
+    if (!query?.ownerId)
+        throw new BexioOAuthError("invalid_config", "ownerId is required");
+    return (await store.findGrants({ ownerId: query.ownerId })).map(toGrant);
+}
+export async function disconnect(ctx, selector) {
+    const record = await resolveGrant(ctx.store, selector);
+    try {
+        const c = await ctx.oidc.config();
+        if (record.refreshToken && c.serverMetadata().revocation_endpoint) {
+            await oidc.tokenRevocation(c, await decryptFor(ctx.cipher, record, record.refreshToken), { token_type_hint: "refresh_token" });
+        }
+    }
+    catch {
+        // Revocation is best effort; the grant is deleted either way.
+    }
+    await ctx.store.deleteGrant(record.id);
+}
+//# sourceMappingURL=grants.js.map

package/dist/grants.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"grants.js","sourceRoot":"","sources":["../src/grants.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,IAAI,MAAM,eAAe,CAAC;AACtC,OAAO,EAAE,SAAS,EAAE,MAAM,MAAM,CAAC;AACjC,OAAO,EAAE,YAAY,EAAE,SAAS,EAAiB,MAAM,aAAa,CAAC;AAGrE,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAC9C,OAAO,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAI7C,gEAAgE;AAChE,MAAM,UAAU,OAAO,CAAC,CAAc;IACpC,OAAO;QACL,EAAE,EAAE,CAAC,CAAC,EAAE;QACR,OAAO,EAAE,CAAC,CAAC,OAAO;QAClB,SAAS,EAAE,CAAC,CAAC,SAAS;QACtB,WAAW,EAAE,CAAC,CAAC,WAAW;QAC1B,MAAM,EAAE,CAAC,CAAC,MAAM;QAChB,QAAQ,EAAE,CAAC,CAAC,QAAQ;QACpB,SAAS,EAAE,CAAC,CAAC,SAAS;QACtB,aAAa,EAAE,CAAC,CAAC,aAAa;QAC9B,IAAI,EAAE,CAAC,CAAC,IAAI;QACZ,MAAM,EAAE,CAAC,CAAC,MAAM;QAChB,KAAK,EAAE,CAAC,CAAC,KAAK;QACd,eAAe,EAAE,CAAC,CAAC,eAAe;QAClC,eAAe,EAAE,CAAC,CAAC,eAAe;QAClC,SAAS,EAAE,CAAC,CAAC,SAAS;QACtB,SAAS,EAAE,CAAC,CAAC,SAAS;KACvB,CAAC;AACJ,CAAC;AAED,6DAA6D;AAC7D,MAAM,UAAU,SAAS,CAAC,MAAmB;IAC3C,OAAO,YAAY,CAAC,MAAM,CAAC,OAAO,EAAE,MAAM,CAAC,SAAS,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC;AACvE,CAAC;AAED,MAAM,UAAU,UAAU,CACxB,MAAmB,EACnB,MAAmB,EACnB,KAAa;IAEb,OAAO,MAAM,CAAC,OAAO,CAAC,KAAK,EAAE,SAAS,CAAC,MAAM,CAAC,CAAC,CAAC;AAClD,CAAC;AAED,wDAAwD;AACxD,MAAM,CAAC,KAAK,UAAU,KAAK,CACzB,MAAmB,EACnB,MAAmB;IAEnB,OAAO;QACL,WAAW,EAAE,MAAM,UAAU,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,WAAW,CAAC;QACjE,SAAS,EAAE,MAAM,CAAC,eAAe;QACjC,KAAK,EAAE,OAAO,CAAC,MAAM,CAAC;KACvB,CAAC;AACJ,CAAC;AAED,8EAA8E;AAC9E,MAAM,CAAC,KAAK,UAAU,YAAY,CAChC,KAAiB,EACjB,QAAuB;IAEvB,IAAI,CAAC,QAAQ,EAAE,OAAO;QACpB,MAAM,IAAI,eAAe,CAAC,gBAAgB,EAAE,qBAAqB,CAAC,CAAC;IACrE,MAAM,IAAI,GAAG,MAAM,KAAK,CAAC,UAAU,CAAC,QAAQ,CAAC,CAAC;IAC9C,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC;QACnB,MAAM,IAAI,eAAe,CAAC,eAAe,EAAE,6BAA6B,CAAC,CAAC;IAC5E,IAAI,IAAI,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACpB,MAAM,IAAI,eAAe,CACvB,iBAAiB,EACjB,qDAAqD,CACtD,CAAC;IACJ,CAAC;IACD,OAAO,IAAI,CAAC,CAAC,CAAE,CAAC;AAClB,CAAC;AAED,sFAAsF;AACtF,MAAM,UAAU,WAAW,CAAC,KAAa;IACvC,IAAI,CAAC;QACH,OAAO,SAAS,CAAC,KAAK,CAAC,CAAC;IAC1B,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,CAAC;IACZ,CAAC;AACH,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAChC,GAAkB,EAClB,MAAgB,EAChB,WAAmB;IAEnB,IAAI,MAAM,CAAC,UAAU,KAAK,SAAS;QAAE,OAAO,MAAM,CAAC;IACnD,IAAI,CAAC;QACH,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,aAAa,CACnC,MAAM,GAAG,CAAC,IAAI,CAAC,MAAM,EAAE,EACvB,WAAW,EACX,OAAO,MAAM,CAAC,GAAG,KAAK,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,gBAAgB,CACpE,CAAC;QACF,OAAO,EAAE,GAAG,IAAI,EAAE,GAAG,MAAM,EAAE,CAAC;IAChC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,MAAM,CAAC;IAChB,CAAC;AACH,CAAC;AAED,8FAA8F;AAC9F,MAAM,CAAC,KAAK,UAAU,UAAU,CAC9B,GAAkB,EAClB,KAQC;IAED,MAAM,QAAQ,GAAG,SAAS,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;IACzC,MAAM,OAAO,GAAG,YAAY,CAC1B,KAAK,CAAC,OAAO,EACb,QAAQ,CAAC,SAAS,EAClB,QAAQ,CAAC,MAAM,CAChB,CAAC;IACF,MAAM,IAAI,GACR,CAAC,MAAM,SAAS,CAAC,GAAG,CAAC,SAAS,EAAE,GAAG,CAAC,UAAU,EAAE,KAAK,CAAC,WAAW,CAAC,CAAC;QACnE,QAAQ,CAAC;IACX,OAAO,GAAG,CAAC,KAAK,CAAC,WAAW,CAAC;QAC3B,OAAO,EAAE,KAAK,CAAC,OAAO;QACtB,GAAG,QAAQ;QACX,IAAI;QACJ,WAAW,EAAE,MAAM,GAAG,CAAC,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,WAAW,EAAE,OAAO,CAAC;QACjE,YAAY,EAAE,KAAK,CAAC,YAAY;YAC9B,CAAC,CAAC,MAAM,GAAG,CAAC,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,YAAY,EAAE,OAAO,CAAC;YACvD,CAAC,CAAC,IAAI;QACR,eAAe,EAAE,KAAK,CAAC,eAAe;QACtC,gBAAgB,EAAE,KAAK,CAAC,gBAAgB;QACxC,KAAK,EAAE,KAAK,CAAC,KAAK;QAClB,GAAG,EAAE,GAAG,CAAC,KAAK,EAAE;KACjB,CAAC,CAAC;AACL,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,UAAU,CAC9B,KAAiB,EACjB,KAA0B;IAE1B,IAAI,CAAC,KAAK,EAAE,OAAO;QACjB,MAAM,IAAI,eAAe,CAAC,gBAAgB,EAAE,qBAAqB,CAAC,CAAC;IACrE,OAAO,CAAC,MAAM,KAAK,CAAC,UAAU,CAAC,EAAE,OAAO,EAAE,KAAK,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;AAC3E,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,UAAU,CAC9B,GAAkB,EAClB,QAAuB;IAEvB,MAAM,MAAM,GAAG,MAAM,YAAY,CAAC,GAAG,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC;IACvD,IAAI,CAAC;QACH,MAAM,CAAC,GAAG,MAAM,GAAG,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC;QAClC,IAAI,MAAM,CAAC,YAAY,IAAI,CAAC,CAAC,cAAc,EAAE,CAAC,mBAAmB,EAAE,CAAC;YAClE,MAAM,IAAI,CAAC,eAAe,CACxB,CAAC,EACD,MAAM,UAAU,CAAC,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,YAAY,CAAC,EACzD,EAAE,eAAe,EAAE,eAAe,EAAE,CACrC,CAAC;QACJ,CAAC;IACH,CAAC;IAAC,MAAM,CAAC;QACP,8DAA8D;IAChE,CAAC;IACD,MAAM,GAAG,CAAC,KAAK,CAAC,WAAW,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;AACzC,CAAC"}

package/dist/idle-sweep.d.ts

@@ -0,0 +1,11 @@
+import type { ClientContext } from "./config.js";
+import { type Duration } from "./duration.js";
+import type { RefreshIdleResult } from "./types.js";
+export declare const DEFAULT_IDLE_LIMIT = 100;
+/** `BexioOAuth.refreshIdle`: refreshes idle grants one after another. */
+export declare function refreshIdle(ctx: ClientContext, options: {
+    idleFor: Duration;
+    limit?: number;
+    timeBudget?: Duration;
+}): Promise<RefreshIdleResult>;
+//# sourceMappingURL=idle-sweep.d.ts.map

package/dist/idle-sweep.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"idle-sweep.d.ts","sourceRoot":"","sources":["../src/idle-sweep.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AACjD,OAAO,EAAQ,KAAK,QAAQ,EAAE,MAAM,eAAe,CAAC;AAGpD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAEpD,eAAO,MAAM,kBAAkB,MAAM,CAAC;AAEtC,yEAAyE;AACzE,wBAAsB,WAAW,CAC/B,GAAG,EAAE,aAAa,EAClB,OAAO,EAAE;IAAE,OAAO,EAAE,QAAQ,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,UAAU,CAAC,EAAE,QAAQ,CAAA;CAAE,GACpE,OAAO,CAAC,iBAAiB,CAAC,CA2D5B"}

package/dist/idle-sweep.js

@@ -0,0 +1,70 @@
+import { toMs } from "./duration.js";
+import { isBexioOAuthError } from "./errors.js";
+import { lockWindow, refreshLocked } from "./refresh.js";
+export const DEFAULT_IDLE_LIMIT = 100;
+/** `BexioOAuth.refreshIdle`: refreshes idle grants one after another. */
+export async function refreshIdle(ctx, options) {
+    const { store, clock } = ctx;
+    const idleMs = toMs(options?.idleFor, "idleFor");
+    const budgetMs = options.timeBudget === undefined
+        ? Infinity
+        : toMs(options.timeBudget, "timeBudget");
+    const startedAt = clock().getTime();
+    const result = {
+        refreshed: 0,
+        skipped: 0,
+        reauthRequired: 0,
+        failed: 0,
+        remaining: 0,
+    };
+    const refreshedBefore = new Date(startedAt - idleMs);
+    const idle = await store.listIdleGrants({
+        refreshedBefore,
+        limit: options.limit ?? DEFAULT_IDLE_LIMIT,
+    });
+    if (idle.length === 0)
+        return result;
+    try {
+        await ctx.oidc.config();
+    }
+    catch {
+        // Bexio unreachable: report, don't throw; the next run retries.
+        result.failed = idle.length;
+        return result;
+    }
+    for (const [index, grant] of idle.entries()) {
+        // Stop before taking the next lock, so a function timeout can't cut a
+        // refresh in half. The oldest grants come first, so the next run
+        // continues where this one stopped.
+        if (clock().getTime() - startedAt >= budgetMs) {
+            result.remaining = idle.length - index;
+            break;
+        }
+        const window = lockWindow(ctx, clock());
+        const locked = await store.acquireRefreshLock({
+            id: grant.id,
+            ...window,
+            refreshedBefore,
+        });
+        if (!locked) {
+            result.skipped++;
+            continue;
+        }
+        try {
+            if (await refreshLocked(ctx, locked, window.lockToken))
+                result.refreshed++;
+            else
+                result.skipped++;
+        }
+        catch (error) {
+            if (isBexioOAuthError(error, "reauth_required")) {
+                result.reauthRequired++;
+            }
+            else {
+                result.failed++;
+            }
+        }
+    }
+    return result;
+}
+//# sourceMappingURL=idle-sweep.js.map

package/dist/idle-sweep.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"idle-sweep.js","sourceRoot":"","sources":["../src/idle-sweep.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,IAAI,EAAiB,MAAM,eAAe,CAAC;AACpD,OAAO,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAChD,OAAO,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAGzD,MAAM,CAAC,MAAM,kBAAkB,GAAG,GAAG,CAAC;AAEtC,yEAAyE;AACzE,MAAM,CAAC,KAAK,UAAU,WAAW,CAC/B,GAAkB,EAClB,OAAqE;IAErE,MAAM,EAAE,KAAK,EAAE,KAAK,EAAE,GAAG,GAAG,CAAC;IAC7B,MAAM,MAAM,GAAG,IAAI,CAAC,OAAO,EAAE,OAAO,EAAE,SAAS,CAAC,CAAC;IACjD,MAAM,QAAQ,GACZ,OAAO,CAAC,UAAU,KAAK,SAAS;QAC9B,CAAC,CAAC,QAAQ;QACV,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,UAAU,EAAE,YAAY,CAAC,CAAC;IAC7C,MAAM,SAAS,GAAG,KAAK,EAAE,CAAC,OAAO,EAAE,CAAC;IACpC,MAAM,MAAM,GAAsB;QAChC,SAAS,EAAE,CAAC;QACZ,OAAO,EAAE,CAAC;QACV,cAAc,EAAE,CAAC;QACjB,MAAM,EAAE,CAAC;QACT,SAAS,EAAE,CAAC;KACb,CAAC;IACF,MAAM,eAAe,GAAG,IAAI,IAAI,CAAC,SAAS,GAAG,MAAM,CAAC,CAAC;IACrD,MAAM,IAAI,GAAG,MAAM,KAAK,CAAC,cAAc,CAAC;QACtC,eAAe;QACf,KAAK,EAAE,OAAO,CAAC,KAAK,IAAI,kBAAkB;KAC3C,CAAC,CAAC;IACH,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,MAAM,CAAC;IACrC,IAAI,CAAC;QACH,MAAM,GAAG,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC;IAC1B,CAAC;IAAC,MAAM,CAAC;QACP,gEAAgE;QAChE,MAAM,CAAC,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC;QAC5B,OAAO,MAAM,CAAC;IAChB,CAAC;IACD,KAAK,MAAM,CAAC,KAAK,EAAE,KAAK,CAAC,IAAI,IAAI,CAAC,OAAO,EAAE,EAAE,CAAC;QAC5C,sEAAsE;QACtE,iEAAiE;QACjE,oCAAoC;QACpC,IAAI,KAAK,EAAE,CAAC,OAAO,EAAE,GAAG,SAAS,IAAI,QAAQ,EAAE,CAAC;YAC9C,MAAM,CAAC,SAAS,GAAG,IAAI,CAAC,MAAM,GAAG,KAAK,CAAC;YACvC,MAAM;QACR,CAAC;QACD,MAAM,MAAM,GAAG,UAAU,CAAC,GAAG,EAAE,KAAK,EAAE,CAAC,CAAC;QACxC,MAAM,MAAM,GAAG,MAAM,KAAK,CAAC,kBAAkB,CAAC;YAC5C,EAAE,EAAE,KAAK,CAAC,EAAE;YACZ,GAAG,MAAM;YACT,eAAe;SAChB,CAAC,CAAC;QACH,IAAI,CAAC,MAAM,EAAE,CAAC;YACZ,MAAM,CAAC,OAAO,EAAE,CAAC;YACjB,SAAS;QACX,CAAC;QACD,IAAI,CAAC;YACH,IAAI,MAAM,aAAa,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,SAAS,CAAC;gBACpD,MAAM,CAAC,SAAS,EAAE,CAAC;;gBAChB,MAAM,CAAC,OAAO,EAAE,CAAC;QACxB,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,IAAI,iBAAiB,CAAC,KAAK,EAAE,iBAAiB,CAAC,EAAE,CAAC;gBAChD,MAAM,CAAC,cAAc,EAAE,CAAC;YAC1B,CAAC;iBAAM,CAAC;gBACN,MAAM,CAAC,MAAM,EAAE,CAAC;YAClB,CAAC;QACH,CAAC;IACH,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC"}