@nacre.work/api 0.0.0 → 0.1.0

package/dist/login.js

@@ -0,0 +1,283 @@
+import { createHash, randomBytes, timingSafeEqual } from 'node:crypto';
+import { hashPassword, needsRehash, spendVerificationTime, verifyPassword, whileAuthenticating, withOrg, } from '@nacre.work/core';
+import { SignJWT } from 'jose';
+/**
+ * Email and password sign-in.
+ *
+ * The last thing in `docs/api.md` that was described and not built. Until now
+ * the only credentials were a token printed by `init` — valid for an hour,
+ * signed with a symmetric secret, and printed into somebody's shell history —
+ * and service account keys, which are for programs.
+ *
+ * SSO is a commercial module. This is the one every self-hoster gets, which is
+ * why it is here rather than there.
+ *
+ * ## Invariant I1 at the one moment there is no token
+ *
+ * "The organization comes from the token, never from a body" governs
+ * authenticated requests. Login is the request that has no token yet, and the
+ * rule still shapes it: the body may name an organization, but only as part of
+ * the lookup key. **What ends up in the token is the `org_id` on the row that
+ * authenticated**, never the string the caller sent. A caller who names one
+ * organization and holds a password in another gets a refusal, not a token for
+ * either.
+ *
+ * The slug is optional because a single-organization installation — which is
+ * what the open core is — should not make people type it. Omitted, the email
+ * has to match exactly one user in the whole installation; zero and several
+ * are the same refusal, so this cannot be used to ask how many organizations
+ * an address appears in.
+ *
+ * ## One refusal, always
+ *
+ * Unknown address, wrong password, wrong organization, disabled account, an
+ * account with no password set: all `401`, same wording, same time spent. The
+ * timing is why `spendVerificationTime` exists — an early return on "no such
+ * user" makes the response time an oracle for which addresses have accounts,
+ * and that would undo the care taken everywhere else about not confirming what
+ * exists.
+ */
+const ACCESS_MIN_SECONDS = 60;
+const digest = (token) => createHash('sha256').update(token).digest('hex');
+/** 32 bytes from the CSPRNG. Opaque — it is looked up, never parsed. */
+const mint = () => randomBytes(32).toString('base64url');
+export class Login {
+    deps;
+    constructor(deps) {
+        this.deps = deps;
+    }
+    get scope() {
+        return this.deps.role === undefined ? {} : { role: this.deps.role };
+    }
+    get clock() {
+        return this.deps.now?.() ?? new Date();
+    }
+    /**
+     * Sign in, or refuse.
+     *
+     * `undefined` for every reason it can fail. The caller turns it into one
+     * `401` with one message.
+     */
+    async login(request) {
+        const email = request.email.trim().toLowerCase();
+        if (email === '' || request.password === '') {
+            // Still spend the time. A short-circuit on an empty field is a free probe
+            // for how long the real path takes.
+            await spendVerificationTime(request.password);
+            return undefined;
+        }
+        const candidate = await this.find(email, request.organization);
+        if (candidate === undefined || candidate.password_hash === null || candidate.disabled_at !== null) {
+            await spendVerificationTime(request.password);
+            return undefined;
+        }
+        if (!(await verifyPassword(request.password, candidate.password_hash)))
+            return undefined;
+        // The only moment the plaintext exists, so the only moment a stored hash
+        // made with weaker parameters can be brought up to date.
+        if (needsRehash(candidate.password_hash)) {
+            const rehashed = await hashPassword(request.password);
+            await withOrg(this.deps.pool, candidate.org_id, (client) => client.query('UPDATE users SET password_hash = $1 WHERE id = $2', [rehashed, candidate.id]), this.scope).catch(() => undefined);
+        }
+        return this.issue(candidate, undefined);
+    }
+    /**
+     * Find the one user this login is about, without saying how many nearly were.
+     *
+     * `organizations` carries no row-level security — an organization is not
+     * inside one — so the slug resolves on an ordinary connection, and the user
+     * is then read through `withOrg` like everything else. That is why the login
+     * path needs no cross-tenant read and no escape hatch: it is two scoped
+     * queries rather than one unscoped one.
+     */
+    async find(email, organization) {
+        if (organization !== undefined && organization.trim() !== '') {
+            const orgId = await this.orgIdForSlug(organization.trim().toLowerCase());
+            if (orgId === undefined)
+                return undefined;
+            return this.userIn(orgId, email);
+        }
+        // No slug. Which is the ordinary case for the single-organization
+        // installation the open core is, and has to stay silent about how many
+        // organizations exist when it is not.
+        const orgIds = await this.allOrgIds();
+        const found = [];
+        for (const orgId of orgIds) {
+            const row = await this.userIn(orgId, email);
+            if (row !== undefined)
+                found.push(row);
+            // Two is already ambiguous; there is nothing to learn from a third, and
+            // stopping keeps the cost of a login independent of how many tenants a
+            // deployment has.
+            if (found.length > 1)
+                return undefined;
+        }
+        return found[0];
+    }
+    async orgIdForSlug(slug) {
+        const client = await this.deps.pool.connect();
+        try {
+            const { rows } = await client.query('SELECT id FROM organizations WHERE slug = $1 AND deleted_at IS NULL', [slug]);
+            return rows[0]?.id;
+        }
+        finally {
+            client.release();
+        }
+    }
+    async allOrgIds() {
+        const client = await this.deps.pool.connect();
+        try {
+            const { rows } = await client.query('SELECT id FROM organizations WHERE deleted_at IS NULL');
+            return rows.map((r) => r.id);
+        }
+        finally {
+            client.release();
+        }
+    }
+    async userIn(orgId, email) {
+        return withOrg(this.deps.pool, orgId, async (client) => {
+            const { rows } = await client.query(`SELECT id, org_id, role, password_hash, disabled_at
+             FROM users WHERE org_id = $1 AND email = $2`, [orgId, email]);
+            return rows[0];
+        }, this.scope);
+    }
+    /**
+     * Exchange a refresh token for a new pair, or refuse.
+     *
+     * Rotation on every use. A token presented after it has been used is not
+     * tolerated as a client retry: the legitimate holder already exchanged it, so
+     * a second presentation means two parties hold the same token and one of them
+     * took it. Which one is unknowable from here, so the whole family is revoked
+     * and both sign in again.
+     */
+    async refresh(token) {
+        const row = await whileAuthenticating(this.deps.pool, async (client) => {
+            const { rows } = await client.query(`SELECT id, org_id, user_id, family_id, expires_at, used_at, revoked_at, token_hash
+             FROM refresh_tokens WHERE token_hash = $1`, [digest(token)]);
+            return rows[0];
+        }, this.scope);
+        if (row === undefined)
+            return undefined;
+        // Constant-time on the hash as well. The lookup already matched it, so this
+        // guards only against a future where the query becomes a prefix match — but
+        // that is exactly the change that would otherwise turn this into an oracle.
+        const presented = Buffer.from(digest(token), 'utf8');
+        const stored = Buffer.from(row.token_hash, 'utf8');
+        if (presented.length !== stored.length || !timingSafeEqual(presented, stored))
+            return undefined;
+        if (row.revoked_at !== null)
+            return undefined;
+        if (row.expires_at.getTime() <= this.clock.getTime())
+            return undefined;
+        // Everything from here is one transaction, serialized on the family.
+        //
+        // The read above is diagnosis, not the decision. Checking `used_at` in
+        // application code and writing it later is a read-modify-write, and under
+        // concurrency every request reads null before any of them writes: eight
+        // simultaneous redemptions of one stolen token all succeeded, each with a
+        // fresh session, and the reuse detection never fired. Rotation without an
+        // atomic claim detects nothing — it only makes theft quieter.
+        //
+        // `used_at IS NULL` in the WHERE clause is the claim, and the advisory lock
+        // is what makes the revocation that follows a loss complete: without it a
+        // revoke whose statement began before this transaction committed cannot see
+        // the row inserted here, so the token the winner just obtained would
+        // survive the revocation meant to catch it.
+        const outcome = await withOrg(this.deps.pool, row.org_id, async (client) => {
+            await client.query('SELECT pg_advisory_xact_lock(hashtext($1))', [row.family_id]);
+            const claimed = await client.query(`UPDATE refresh_tokens SET used_at = now()
+            WHERE id = $1 AND used_at IS NULL AND revoked_at IS NULL
+            RETURNING id`, [row.id]);
+            if (claimed.rows[0] === undefined)
+                return 'lost';
+            const { rows } = await client.query(`SELECT id, org_id, role, password_hash, disabled_at
+             FROM users WHERE id = $1 AND org_id = $2`, [row.user_id, row.org_id]);
+            const user = rows[0];
+            if (user === undefined || user.disabled_at !== null)
+                return 'gone';
+            return this.issue(user, row.family_id, client);
+        }, this.scope);
+        if (outcome === 'lost') {
+            // Someone already spent this one. Two parties hold the same token and
+            // there is no way to tell which is genuine, so the session ends for both.
+            await this.revokeFamily(row.org_id, row.family_id);
+            return undefined;
+        }
+        if (outcome === 'gone') {
+            // Disabling an account has to end its sessions, or it only stops new
+            // ones. The claim above is committed, so the token is spent either way —
+            // a refusal here must not leave it redeemable.
+            await this.revokeFamily(row.org_id, row.family_id);
+            return undefined;
+        }
+        return outcome;
+    }
+    /** Sign out. Ends the family, not just this token. */
+    async logout(token) {
+        const row = await whileAuthenticating(this.deps.pool, async (client) => {
+            const { rows } = await client.query('SELECT org_id, family_id FROM refresh_tokens WHERE token_hash = $1 AND revoked_at IS NULL', [digest(token)]);
+            return rows[0];
+        }, this.scope);
+        if (row === undefined)
+            return false;
+        await this.revokeFamily(row.org_id, row.family_id);
+        return true;
+    }
+    /**
+     * End every token descended from one login.
+     *
+     * Takes the same advisory lock the rotation path takes, and that is what
+     * makes it complete rather than approximately complete. Without it the two
+     * interleave badly: a statement's snapshot is fixed when the statement
+     * starts, so a revoke that begins before a rotation commits will not see the
+     * row that rotation inserts — and the token the racing party just obtained
+     * survives the revocation that was supposed to catch it. Serialized on the
+     * family, the revoke either runs first (and the rotation then finds the
+     * family revoked) or runs second (and sees the new row).
+     */
+    async revokeFamily(orgId, familyId) {
+        await withOrg(this.deps.pool, orgId, async (client) => {
+            await client.query('SELECT pg_advisory_xact_lock(hashtext($1))', [familyId]);
+            await client.query('UPDATE refresh_tokens SET revoked_at = now() WHERE family_id = $1 AND revoked_at IS NULL', [familyId]);
+        }, this.scope);
+    }
+    /**
+     * Mint an access token and the refresh token that succeeds it.
+     *
+     * `family` carries across a rotation so the whole chain from one login can be
+     * revoked together; a fresh login starts a new one, so signing out of one
+     * device does not sign out of the others.
+     */
+    async issue(user, family, client) {
+        const ttl = Math.max(ACCESS_MIN_SECONDS, this.deps.accessTokenTtl);
+        const now = this.clock;
+        const accessToken = await new SignJWT({
+            // From the row that authenticated, never from the request. This is the
+            // line invariant I1 is about.
+            org: user.org_id,
+            principal_type: 'user',
+            role: user.role,
+        })
+            .setProtectedHeader({ alg: 'HS256' })
+            .setSubject(user.id)
+            .setIssuer(this.deps.issuer)
+            .setAudience(this.deps.audience)
+            .setIssuedAt(Math.floor(now.getTime() / 1000))
+            .setExpirationTime(Math.floor(now.getTime() / 1000) + ttl)
+            .sign(this.deps.key);
+        const refreshToken = mint();
+        const expiresAt = new Date(now.getTime() + this.deps.refreshTokenTtl * 1000);
+        const insert = (client) => client.query(`INSERT INTO refresh_tokens (org_id, user_id, token_hash, family_id, expires_at)
+         VALUES ($1, $2, $3, COALESCE($4::uuid, gen_random_uuid()), $5)`, [user.org_id, user.id, digest(refreshToken), family ?? null, expiresAt]);
+        // On a rotation the caller hands in its own transaction, so the claim and
+        // the token that replaces it commit together — a crash between them would
+        // otherwise spend a token and issue nothing, ending a session for no
+        // reason. A fresh login has no transaction to join and opens its own.
+        if (client !== undefined)
+            await insert(client);
+        else
+            await withOrg(this.deps.pool, user.org_id, insert, this.scope);
+        return { accessToken, refreshToken, expiresIn: ttl, orgId: user.org_id, userId: user.id };
+    }
+}
+//# sourceMappingURL=login.js.map

package/dist/login.js.map

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

package/dist/main.js

@@ -1,6 +1,10 @@
 import { createHash } from 'node:crypto';
-import { collectDatabaseGauges, createMetrics, createPool, loadConfig, Registry, VectorStore, vectorName, withOrg, ConfigError, } from '@nacre.work/core';
-import { HttpEmbedder, NacreIngest, NacreSearchService, PostgresAudit, PostgresDocuments, PostgresGrants, PostgresJobs, PostgresLayers, } from './adapters.js';
+import { collectDatabaseGauges, createMetrics, createPool, loadConfig, loadJwtKeys, protectedResourceMetadata, Redis, Registry, VectorStore, withOrg, ConfigError, installGuards, onListenError, } from '@nacre.work/core';
+import { HttpEmbedder, NacreIngest, NacreSearchService, PostgresAudit, PostgresAuditReader, PostgresDocuments, PostgresGrants, PostgresJobs, PostgresLayers, PostgresReindex, PostgresWorkspaces, } from './adapters.js';
+import { Idempotency } from './idempotency.js';
+import { Login } from './login.js';
+import { rerankerFor } from './rerank.js';
+import { RateLimiter } from './limits.js';
 import { PostgresServiceAccounts, PostgresServiceKeys } from './service-keys.js';
 import { createApi } from './server.js';
 /**
@@ -11,70 +15,140 @@ import { createApi } from './server.js';
  * below this line has a fallback.
  */
 const APP_ROLE = 'nacre_app';
-function jwtKey(config) {
-    // Development uses a symmetric secret. Production is meant to load an Ed25519
-    // key through NACRE_JWT_PRIVATE_KEY_REF; until that lands, refusing is the
-    // honest behaviour — a hardcoded fallback here would be a signing key anyone
-    // reading the source can forge tokens with.
-    const secret = process.env.NACRE_JWT_SECRET;
-    if (secret === undefined || secret.length < 32) {
-        throw new ConfigError([
-            'NACRE_JWT_SECRET is not set, or is shorter than 32 bytes. ' +
-                'Asymmetric keys through NACRE_JWT_PRIVATE_KEY_REF are not implemented yet; ' +
-                'until they are, this is required and there is no default.',
-        ]);
-    }
-    void config;
-    return new TextEncoder().encode(secret);
-}
 async function main() {
     const config = loadConfig();
-    const key = jwtKey({});
+    const { key, alsoAccept } = loadJwtKeys();
     const pool = createPool({ connectionString: config.pgUrl, max: config.pgPoolMax });
     const vectors = new VectorStore(config.qdrantApiKey === undefined
         ? { url: config.qdrantUrl }
         : { url: config.qdrantUrl, apiKey: config.qdrantApiKey });
-    const embedder = new HttpEmbedder(config.embeddingEndpoint, config.embeddingModel, config.embeddingDim);
-    // Slugs change rarely and are read on every search. A tiny cache keyed on the
-    // organization keeps a search from costing an extra round trip; it is not
-    // permission data, so staleness here cannot widen access.
-    const slugs = new Map();
-    const orgSlug = async (orgId) => {
-        const cached = slugs.get(orgId);
-        if (cached !== undefined)
-            return cached;
-        const found = await withOrg(pool, orgId, async (client) => {
-            const { rows } = await client.query('SELECT slug FROM organizations WHERE id = $1 AND deleted_at IS NULL', [orgId]);
-            return rows[0]?.slug;
-        }, { role: APP_ROLE });
-        if (found !== undefined)
-            slugs.set(orgId, found);
-        return found;
-    };
     const registry = new Registry();
     const metrics = createMetrics(registry);
     registry.collect(collectDatabaseGauges(pool, metrics, APP_ROLE));
+    // Redis has been required configuration, and in every Compose profile with
+    // the API waiting on its healthcheck, since before anything connected to it.
+    // Rate limiting and Idempotency-Key are what it was declared for.
+    const redis = new Redis({ url: config.redisUrl });
+    const limitPolicies = {
+        search: { limit: config.rateSearchPerMin, windowSeconds: 60 },
+        ingest: { limit: config.rateIngestPerHour, windowSeconds: 3600 },
+        // Per address rather than per organization — there is no organization until
+        // the sign-in succeeds, and what this defends is one account's password.
+        login: { limit: config.rateLoginPer15Min, windowSeconds: 900 },
+        // And per client, which is what the address limit does not do: a spray
+        // across ten thousand addresses never repeats a key. Looser on purpose,
+        // because a whole office behind one NAT is one source here.
+        login_source: { limit: config.rateLoginSourcePer15Min, windowSeconds: 900 },
+    };
+    const limits = new RateLimiter({
+        redis,
+        policies: limitPolicies,
+        onDegraded: (resource, error) => {
+            // Allowed through, and said so. A rate limit is availability protection
+            // rather than an authorization control, so failing closed here would
+            // trade a rare over-serve for a certain outage — the opposite of the
+            // rule for permissions, and deliberately so.
+            console.warn(JSON.stringify({
+                msg: 'rate limit check unavailable; request allowed',
+                resource,
+                error: String(error).slice(0, 200),
+            }));
+        },
+    });
+    // Undefined unless the deployment configured one — `minimal` has no
+    // reranker by definition, which is what keeps it runnable without a GPU.
+    const reranker = rerankerFor(config);
+    const idempotency = new Idempotency({
+        redis,
+        onDegraded: (error) => {
+            console.warn(JSON.stringify({
+                msg: 'idempotency cache unavailable; request processed uncached',
+                error: String(error).slice(0, 200),
+            }));
+        },
+    });
+    const login = new Login({
+        pool,
+        key,
+        issuer: config.jwtIssuer,
+        audience: config.jwtAudience,
+        accessTokenTtl: config.accessTokenTtl,
+        refreshTokenTtl: config.refreshTokenTtl,
+        role: APP_ROLE,
+    });
+    // What this process cannot serve a request without. S3 is in the documented
+    // list and is not checked, because nothing in the tree reads it yet — a probe
+    // that reported on a dependency the code never uses would be reporting on
+    // nothing. The embedder is not checked either: it is an external endpoint an
+    // operator supplies, a search fails loudly without it, and making readiness
+    // depend on somebody else's uptime turns their outage into a rollout that
+    // never completes.
+    const ready = async () => {
+        const [postgres, qdrant, redisUp] = await Promise.all([
+            withOrg(pool, '00000000-0000-0000-0000-000000000000', async (c) => {
+                await c.query('SELECT 1');
+                return true;
+            }, { role: APP_ROLE }).catch(() => false),
+            vectors.ready().catch(() => false),
+            redis.ping().catch(() => false),
+        ]);
+        return { postgres, qdrant, redis: redisUp };
+    };
     const server = createApi({
         verify: {
             key,
+            // Empty outside a rotation. During one it carries the key being retired,
+            // so tokens already in the wild keep verifying until they expire.
+            ...(alsoAccept.length === 0 ? {} : { alsoAccept }),
             issuer: config.jwtIssuer,
             audience: config.jwtAudience,
             serviceKeys: new PostgresServiceKeys(pool, APP_ROLE),
         },
         metrics: registry,
-        documents: new PostgresDocuments(pool, APP_ROLE),
+        resourceMetadata: protectedResourceMetadata({
+            canonicalUrl: config.canonicalUrl,
+            ...(config.oauthAuthorizationServer === ''
+                ? {}
+                : { authorizationServer: config.oauthAuthorizationServer }),
+        }),
+        // The request path writes what it measures. Four of these were registered
+        // and never written, so /metrics served zeros forever — which reads as
+        // health rather than as absence.
+        observe: metrics,
+        ready,
+        maxBodyBytes: config.maxDocumentBytes,
+        limits,
+        limitPolicies,
+        trustProxy: config.trustProxy,
+        ...(config.metricsToken === undefined ? {} : { metricsToken: config.metricsToken }),
+        idempotency,
+        login,
+        auditReader: new PostgresAuditReader(pool, APP_ROLE),
+        reindex: new PostgresReindex(pool, vectors, APP_ROLE),
+        documents: new PostgresDocuments(pool, vectors, APP_ROLE),
         search: new NacreSearchService({
             pool,
             vectors,
-            embedder,
-            orgSlug,
-            vectorName: vectorName(config.embeddingModel, config.embeddingDim),
+            embedderFor: HttpEmbedder.pool(),
             role: APP_ROLE,
+            ...(reranker === undefined ? {} : { reranker }),
+            rerankCandidates: config.rerankCandidates,
+            onRerankFailed: (error) => {
+                // Answered in fusion order rather than not at all. Reranking decides
+                // ordering over candidates the index already filtered by permission,
+                // so this is a quality degradation and not a permissions one — and an
+                // operator who turned it on is entitled to know it is not running.
+                console.warn(JSON.stringify({
+                    msg: 'reranking failed; results are in fusion order',
+                    error: String(error).slice(0, 200),
+                }));
+            },
         }),
-        ingest: new NacreIngest({ pool, tombstone: vectors, orgSlug, role: APP_ROLE }),
+        ingest: new NacreIngest({ pool, tombstone: vectors, role: APP_ROLE }),
         audit: new PostgresAudit(pool, APP_ROLE),
         jobs: new PostgresJobs(pool, APP_ROLE),
-        layers: new PostgresLayers(pool, APP_ROLE),
+        layers: new PostgresLayers(pool, vectors, APP_ROLE),
+        workspaces: new PostgresWorkspaces(pool, APP_ROLE),
         grants: new PostgresGrants(pool, APP_ROLE),
         serviceAccounts: new PostgresServiceAccounts(pool, APP_ROLE),
     });
@@ -82,25 +156,34 @@ async function main() {
     server.listen(port, () => {
         // The fingerprint, never the secret. An operator needs to know which key is
         // in use when two environments disagree; nobody needs the key in a log.
-        const fingerprint = createHash('sha256').update(key).digest('hex').slice(0, 12);
+        const print = (k) => `sha256:${createHash('sha256').update(k).digest('hex').slice(0, 12)}`;
         console.log(JSON.stringify({
             msg: 'api listening',
             port,
             env: config.env,
             issuer: config.jwtIssuer,
-            jwt_key: `sha256:${fingerprint}`,
+            jwt_key: print(key),
+            // Present only during a rotation, which is exactly when an operator is
+            // reading this line. Its absence is how they know the rotation is
+            // finished and the old key is out.
+            ...(alsoAccept.length === 0 ? {} : { jwt_key_previous: alsoAccept.map(print) }),
         }));
     });
-    const shutdown = (signal) => {
-        console.log(JSON.stringify({ msg: 'shutting down', signal }));
+    onListenError(server, 'api', port);
+    installGuards({
+        service: 'api',
         // Stop accepting, let in-flight requests finish, then release the pool.
-        // Dropping a request mid-flight would leave its audit event unwritten.
-        server.close(() => {
-            void pool.end().then(() => process.exit(0));
-        });
-    };
-    process.on('SIGTERM', () => shutdown('SIGTERM'));
-    process.on('SIGINT', () => shutdown('SIGINT'));
+        // Dropping a request mid-flight would leave its audit event unwritten —
+        // but `server.close` waits without a bound, so `installGuards` puts one on
+        // it: one request stuck on a slow dependency used to mean the callback
+        // never ran, the pool was never released, and the orchestrator SIGKILLed at
+        // the end of its grace period. Every rolling deploy was an abrupt one.
+        shutdown: async () => {
+            await new Promise((resolve) => server.close(() => resolve()));
+            redis.close();
+            await pool.end();
+        },
+    });
 }
 main().catch((error) => {
     if (error instanceof ConfigError) {

package/dist/main.js.map

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

package/dist/pagination.d.ts

@@ -0,0 +1,72 @@
+import { type Problem } from './errors.js';
+/**
+ * Cursor pagination, and never offset.
+ *
+ * `docs/api.md` forbids offset on two grounds and both are real. It breaks
+ * under concurrent inserts — a row added while a client pages through shifts
+ * everything after it, so the client sees an item twice or not at all. And it
+ * invites enumeration: `?offset=10000` is a question about how much exists,
+ * which on a permission-scoped collection is a question the caller has no right
+ * to ask.
+ *
+ * The cursor is a position, not an index. It carries the sort key of the last
+ * item returned, so the next page is "everything after this one" — which is
+ * stable no matter what was inserted in between, and says nothing about size.
+ *
+ * ## Opaque, and only just
+ *
+ * It is base64url of `created_at|id`, which anyone can decode, and that is
+ * fine: both values are already in the response they came from. What matters is
+ * that it is *treated* as opaque — a client that parses it and constructs its
+ * own has built a dependency on a format that is allowed to change, and the
+ * signature check below is what tells them so before it becomes their problem.
+ *
+ * It is not signed. A forged cursor selects a different page of the same
+ * caller's own collection, which they could reach by paging anyway; signing it
+ * would defend nothing and imply a guarantee that does not exist.
+ */
+export declare const MAX_LIMIT = 200;
+export declare const DEFAULT_LIMIT = 50;
+export interface Position {
+    /** The sort key of the last item on the previous page. */
+    readonly createdAt: string;
+    /** Tie-breaker, because timestamps collide under a bulk insert. */
+    readonly id: string;
+}
+export interface Page {
+    readonly limit: number;
+    readonly after: Position | undefined;
+}
+export declare function encodeCursor(position: Position): string;
+/**
+ * Read `?limit=` and `?cursor=`, or explain what is wrong with them.
+ *
+ * `?offset=` is refused rather than ignored. Ignoring it gives a client the
+ * first page over and over while they believe they are paging, which is the
+ * failure that takes an afternoon to see.
+ */
+export declare function readPage(params: URLSearchParams, instance: string, requestId: string): Page | Problem;
+/**
+ * What a paginated port returns.
+ *
+ * `items` and the cursor are separate because they are not always derived from
+ * the same row. Where a collection is filtered in application code after the
+ * database has already applied the cursor — grants are, because who may see one
+ * is decided by walking the scope tree — the cursor has to come from the last
+ * row **fetched** rather than the last one returned. Taking it from the last
+ * returned row would skip everything the filter removed after it.
+ *
+ * The consequence, which callers have to know: **a page may hold fewer than
+ * `limit` items, and an empty page does not mean the end.** `nextCursor` is the
+ * only signal that more exist.
+ */
+export interface PageResult<T> {
+    readonly items: readonly T[];
+    readonly nextCursor: string | null;
+}
+/**
+ * The common case: rows come back already filtered, so the cursor is the last
+ * one returned and a short page means the collection is exhausted.
+ */
+export declare function pageOf<T>(rows: readonly T[], page: Page | undefined, positionOf: (row: T) => Position): PageResult<T>;
+//# sourceMappingURL=pagination.d.ts.map