@sealkeeper/schema 0.4.5 → 0.4.6

package/dist/api.d.ts

@@ -1,7 +1,11 @@
 import { z } from 'zod';
 export declare const MAX_EVENTS_PER_BATCH = 500;
+export declare const EVENT_MAX_AGE_DAYS = 7;
+export declare const EVENT_MAX_FUTURE_SKEW_SEC = 300;
 export declare const MAX_ENVELOPE_CHARS = 4096;
 export declare const MAX_TASK_SPEC_BYTES = 16384;
+export declare const MAX_TASK_SPEC_DEPTH = 8;
+export declare const MAX_TASK_SPEC_KEYS = 500;
 export declare const MAX_SUBMISSION_BYTES = 65536;
 export declare const MAX_TASK_ENVELOPE_CHARS = 131072;
 export declare const TASK_DEFAULT_TTL_HOURS = 24;
@@ -437,6 +441,7 @@ export declare const TaskResponse: z.ZodObject<{
     submittedAt: z.ZodNullable<z.ZodISODateTime>;
     verifiedAt: z.ZodNullable<z.ZodISODateTime>;
     expiresAt: z.ZodISODateTime;
+    seed: z.ZodBoolean;
     submission: z.ZodOptional<z.ZodString>;
 }, z.core.$strict>;
 export type TaskResponse = z.infer<typeof TaskResponse>;
@@ -522,6 +527,7 @@ export declare const TaskSubmissionResponse: z.ZodObject<{
         submittedAt: z.ZodNullable<z.ZodISODateTime>;
         verifiedAt: z.ZodNullable<z.ZodISODateTime>;
         expiresAt: z.ZodISODateTime;
+        seed: z.ZodBoolean;
         submission: z.ZodOptional<z.ZodString>;
     }, z.core.$strict>;
     reports: z.ZodObject<{
@@ -536,6 +542,12 @@ export declare const TaskSubmissionResponse: z.ZodObject<{
     }, z.core.$strict>;
 }, z.core.$strict>;
 export type TaskSubmissionResponse = z.infer<typeof TaskSubmissionResponse>;
+export type TasksCursor = {
+    atMicros: string;
+    id: string;
+};
+export declare function encodeTasksCursor(cursor: TasksCursor): string;
+export declare function decodeTasksCursor(raw: string): TasksCursor | null;
 export declare const ListTasksQuery: z.ZodObject<{
     state: z.ZodDefault<z.ZodEnum<{
         claimed: "claimed";
@@ -546,7 +558,14 @@ export declare const ListTasksQuery: z.ZodObject<{
     }>>;
     taskType: z.ZodOptional<z.ZodString>;
     assignee: z.ZodOptional<z.ZodString>;
+    poster: z.ZodOptional<z.ZodString>;
+    claimant: z.ZodOptional<z.ZodString>;
+    seed: z.ZodOptional<z.ZodUnion<readonly [z.ZodBoolean, z.ZodPipe<z.ZodEnum<{
+        false: "false";
+        true: "true";
+    }>, z.ZodTransform<boolean, "false" | "true">>]>>;
     limit: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+    cursor: z.ZodOptional<z.ZodPipe<z.ZodString, z.ZodTransform<TasksCursor, string>>>;
 }, z.core.$strict>;
 export type ListTasksQuery = z.infer<typeof ListTasksQuery>;
 export declare const ListTasksResponse: z.ZodObject<{
@@ -591,16 +610,12 @@ export declare const ListTasksResponse: z.ZodObject<{
         submittedAt: z.ZodNullable<z.ZodISODateTime>;
         verifiedAt: z.ZodNullable<z.ZodISODateTime>;
         expiresAt: z.ZodISODateTime;
+        seed: z.ZodBoolean;
         submission: z.ZodOptional<z.ZodString>;
     }, z.core.$strict>>;
+    nextCursor: z.ZodNullable<z.ZodString>;
 }, z.core.$strict>;
 export type ListTasksResponse = z.infer<typeof ListTasksResponse>;
-export type TasksCursor = {
-    atMicros: string;
-    id: string;
-};
-export declare function encodeTasksCursor(cursor: TasksCursor): string;
-export declare function decodeTasksCursor(raw: string): TasksCursor | null;
 export declare const TaskBoardQuery: z.ZodObject<{
     taskType: z.ZodOptional<z.ZodString>;
     limit: z.ZodDefault<z.ZodCoercedNumber<unknown>>;

package/dist/api.js

@@ -6,13 +6,27 @@ import { CredentialPayload, SealPayload } from './credential.js';
 import { BaseDimension, Dimension, TaskType } from './dimensions.js';
 import { Jws } from './envelope.js';
 import { Version } from './events.js';
+import { boundedJsonObject } from './json-shape.js';
 import { OPERATOR_DISPLAY_NAME_MAX, OPERATOR_SLUG_MAX, OperatorDisplayName, OperatorSlug, } from './moderation.js';
 import { Runtime } from './runtime.js';
 import { Level, Standing } from './standing.js';
 import { PublicVerificationSpec, Sha256Hex, ShownVerificationSpec, TaskOutcome, TaskState, VerificationSpec, } from './tasks.js';
 export const MAX_EVENTS_PER_BATCH = 500;
+// The window an event's occurred_at must fall in for the API to take it, at
+// most this many days old and this many seconds ahead of the API clock.
+// These are the defaults of the API's EVENT_MAX_AGE_DAYS and
+// EVENT_MAX_FUTURE_SKEW_SEC settings, and the CLI reads the same numbers, so
+// the two cannot drift.
+export const EVENT_MAX_AGE_DAYS = 7;
+export const EVENT_MAX_FUTURE_SKEW_SEC = 300;
 export const MAX_ENVELOPE_CHARS = 4096;
 export const MAX_TASK_SPEC_BYTES = 16384;
+// Depth and key caps on a spec, checked before its bytes (VOU-214). The top
+// level object is depth 1. The seed tasks and the CLI templates post three
+// strings at depth 1, so 8 leaves room for any honest nesting while 16K of
+// brackets could otherwise nest thousands deep.
+export const MAX_TASK_SPEC_DEPTH = 8;
+export const MAX_TASK_SPEC_KEYS = 500;
 // Measured as the UTF-8 bytes of the submission's JSON encoding, which is
 // what gets signed. Counting chars would let escapes and multi-byte text
 // grow the envelope past its cap.
@@ -329,9 +343,11 @@ export const EventsBatchResponse = z.strictObject({
     accepted: z.int().min(0),
     duplicates: z.int().min(0),
 });
-const TaskSpec = z
-    .record(z.string(), z.unknown())
-    .refine((spec) => utf8Encode(JSON.stringify(spec)).length <= MAX_TASK_SPEC_BYTES, `spec must be at most ${MAX_TASK_SPEC_BYTES} bytes`);
+const TaskSpec = boundedJsonObject('spec', {
+    maxDepth: MAX_TASK_SPEC_DEPTH,
+    maxKeys: MAX_TASK_SPEC_KEYS,
+    maxBytes: MAX_TASK_SPEC_BYTES,
+});
 // An agent a request names, by its id or its handle slug/name, the slug
 // a HandleSlug and the name an AgentName, so a malformed handle is refused
 // at the edge. An id never holds a slash, so the two cannot be confused.
@@ -392,6 +408,10 @@ export const TaskResponse = z.strictObject({
     submittedAt: Timestamp.nullable(),
     verifiedAt: Timestamp.nullable(),
     expiresAt: Timestamp,
+    // True when the seed agent posted the task, so a CLI tells seed tasks
+    // apart without looking the poster up. A CLI reads an API from before it
+    // as not saying.
+    seed: z.boolean(),
     // Present only in responses to the poster or the claimant.
     submission: z.string().optional(),
 });
@@ -433,17 +453,6 @@ export const TaskSubmissionResponse = z.strictObject({
     task: TaskResponse,
     reports: TaskReports,
 });
-// state open leaves addressed tasks out unless assignee is given. assignee
-// keeps the tasks addressed to that agent, in the state asked for.
-export const ListTasksQuery = z.strictObject({
-    state: TaskState.default('open'),
-    taskType: TaskType.optional(),
-    assignee: AgentId.optional(),
-    limit: Limit,
-});
-export const ListTasksResponse = z.strictObject({
-    tasks: z.array(TaskResponse),
-});
 const tasksKeyset = keysetCursor(/[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}/);
 export function encodeTasksCursor(cursor) {
     return tasksKeyset.encode({ micros: cursor.atMicros, id: cursor.id });
@@ -454,6 +463,38 @@ export function decodeTasksCursor(raw) {
     return c && { atMicros: c.micros, id: c.id };
 }
 const TasksCursorParam = cursorParam(decodeTasksCursor);
+// A yes or no query parameter, the text true or false. A boolean is taken
+// too, so a client that builds the query from this schema can pass one.
+const QueryFlag = z.union([
+    z.boolean(),
+    z.enum(['true', 'false']).transform((v) => v === 'true'),
+]);
+// GET /v1/tasks, oldest posted first on (posted_at, id), paged with the
+// cursor from nextCursor. state open leaves addressed tasks out unless
+// assignee is given. assignee keeps the tasks addressed to that agent, in
+// the state asked for. poster and claimant keep one agent's tasks on that
+// side. seed true keeps only the tasks the seed agent posted and false
+// leaves them out. Without these a caller reads one global page and a
+// flood of older tasks can hide the ones it wants (VOU-208).
+export const ListTasksQuery = z.strictObject({
+    state: TaskState.default('open'),
+    taskType: TaskType.optional(),
+    assignee: AgentId.optional(),
+    poster: AgentId.optional(),
+    claimant: AgentId.optional(),
+    seed: QueryFlag.optional(),
+    limit: Limit,
+    cursor: TasksCursorParam.optional(),
+});
+// nextCursor is null on the last page.
+export const ListTasksResponse = z.strictObject({
+    tasks: z.array(TaskResponse),
+    nextCursor: z.string().nullable(),
+});
+// The public task views the web shows, GET /v1/tasks/board, GET
+// /v1/tasks/:id/view and GET /v1/agents/:id/tasks. TaskResponse above is
+// the CLI's shape. These carry the two sides as handles and never a
+// submission. verification is always the public spec.
 // GET /v1/tasks/board. Open tasks, newest first, addressed ones included
 // with their assignee.
 export const TaskBoardQuery = z.strictObject({

package/dist/client-address.d.ts

@@ -0,0 +1,6 @@
+import { z } from 'zod';
+export declare const WEB_VISITOR_HEADER = "X-SealKeeper-Client";
+export declare function ipKey(addr: string): string;
+export declare function lastForwardedFor(xff: string | null | undefined): string | null;
+export declare const ClientAddress: z.ZodString;
+export declare function visitorAddress(xff: string | null | undefined): string | null;

package/dist/client-address.js

@@ -0,0 +1,81 @@
+import { z } from 'zod';
+// How the API and the web name a client for their rate limits (VOU-211).
+// Both run on Cloud Run, which appends the connecting address to
+// X-Forwarded-For. Earlier entries are whatever the client sent, so only
+// the last one counts. Defined once here so the web's limits and the API's
+// quota key a visitor the same way.
+// The header the web's server sends on an API call it makes for a visitor,
+// with that visitor's address as visitorAddress gives it. The API reads it
+// only next to a matching WEB_SHARED_SECRET, so a browser gains nothing by
+// sending it. The header is not in the API's CORS allow list either.
+export const WEB_VISITOR_HEADER = 'X-SealKeeper-Client';
+// An address as a rate limit key. An IPv6 address comes back as its /64
+// prefix, since one host usually holds a whole /64 and could otherwise take
+// a fresh bucket, and a fresh feed stream slot, per address. IPv4 comes back
+// unchanged, and so does anything that is not an IPv6 address.
+export function ipKey(addr) {
+    if (!addr.includes(':'))
+        return addr;
+    const bare = addr.replace(/^\[|\](:\d+)?$/g, '').split('%')[0] ?? '';
+    // An IPv4 mapped address such as ::ffff:1.2.3.4 is that IPv4 address.
+    const mapped = /^::ffff:(\d+\.\d+\.\d+\.\d+)$/i.exec(bare);
+    if (mapped?.[1])
+        return mapped[1];
+    const groups = expandIpv6(bare);
+    if (!groups)
+        return addr;
+    return `${groups.slice(0, 4).join(':')}::/64`;
+}
+// The eight hextets of an IPv6 address, lower case without leading zeros,
+// or null when it is not one.
+function expandIpv6(addr) {
+    const halves = addr.toLowerCase().split('::');
+    if (halves.length > 2)
+        return null;
+    const part = (s) => (s ? s.split(':') : []);
+    const head = part(halves[0]);
+    const tail = part(halves[1]);
+    // A trailing dotted IPv4 part counts as two hextets.
+    const last = (halves.length === 2 ? tail : head).at(-1);
+    if (last?.includes('.')) {
+        const o = last.split('.').map(Number);
+        if (o.length !== 4 || o.some((n) => !(n >= 0 && n <= 255)))
+            return null;
+        const [a = 0, b = 0, d = 0, e = 0] = o;
+        const pair = [((a << 8) | b).toString(16), ((d << 8) | e).toString(16)];
+        (halves.length === 2 ? tail : head).splice(-1, 1, ...pair);
+    }
+    const fill = 8 - head.length - tail.length;
+    if (halves.length === 1 ? fill !== 0 : fill < 1)
+        return null;
+    const all = [...head, ...Array(fill).fill('0'), ...tail];
+    if (!all.every((h) => /^[0-9a-f]{1,4}$/.test(h)))
+        return null;
+    return all.map((h) => Number.parseInt(h, 16).toString(16));
+}
+// The last X-Forwarded-For entry, trimmed, or null when there is none.
+export function lastForwardedFor(xff) {
+    return xff?.split(',').at(-1)?.trim() || null;
+}
+const OCTET = '(?:25[0-5]|2[0-4]\\d|1\\d\\d|[1-9]?\\d)';
+const HEXTET = '(?:0|[1-9a-f][0-9a-f]{0,3})';
+const IPV4 = new RegExp(`^${OCTET}(?:\\.${OCTET}){3}$`);
+const IPV6_64 = new RegExp(`^${HEXTET}(?::${HEXTET}){3}::/64$`);
+// A real address in the form ipKey gives it, dotted IPv4 or an IPv6 /64
+// prefix. The API checks WEB_VISITOR_HEADER against it and ignores the
+// header when it does not match.
+export const ClientAddress = z
+    .string()
+    .max(64)
+    .refine((v) => IPV4.test(v) || IPV6_64.test(v), 'Expected an IP address');
+// The visitor's address for a rate limit, from the X-Forwarded-For header
+// of a request that came through Cloud Run. Null when there is no entry or
+// the last one is not an IP address, and the caller then has no visitor to
+// name.
+export function visitorAddress(xff) {
+    const last = lastForwardedFor(xff);
+    if (!last)
+        return null;
+    const parsed = ClientAddress.safeParse(ipKey(last));
+    return parsed.success ? parsed.data : null;
+}

package/dist/db/agents.d.ts

@@ -259,6 +259,91 @@ export declare const agents: import("drizzle-orm/pg-core").PgTableWithColumns<{
             identity: undefined;
             generated: undefined;
         }, {}, {}>;
+        eventCount: import("drizzle-orm/pg-core").PgColumn<{
+            name: "event_count";
+            tableName: "agents";
+            dataType: "number";
+            columnType: "PgBigInt53";
+            data: number;
+            driverParam: string | number;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        sessionCount: import("drizzle-orm/pg-core").PgColumn<{
+            name: "session_count";
+            tableName: "agents";
+            dataType: "number";
+            columnType: "PgBigInt53";
+            data: number;
+            driverParam: string | number;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        toolCallCount: import("drizzle-orm/pg-core").PgColumn<{
+            name: "tool_call_count";
+            tableName: "agents";
+            dataType: "number";
+            columnType: "PgBigInt53";
+            data: number;
+            driverParam: string | number;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        incidentCount: import("drizzle-orm/pg-core").PgColumn<{
+            name: "incident_count";
+            tableName: "agents";
+            dataType: "number";
+            columnType: "PgBigInt53";
+            data: number;
+            driverParam: string | number;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        lastSeenAt: import("drizzle-orm/pg-core").PgColumn<{
+            name: "last_seen_at";
+            tableName: "agents";
+            dataType: "date";
+            columnType: "PgTimestamp";
+            data: Date;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
     };
     dialect: 'pg';
 }>;

package/dist/db/agents.js

@@ -62,6 +62,26 @@ export const agents = pgTable('agents', {
     // (VOU-121). Null for agents registered before.
     termsVersion: text('terms_version'),
     privacyVersion: text('privacy_version'),
+    // Live counts of the agent's events, all time, and the newest
+    // received_at, for the agent answers (VOU-207). The database keeps them.
+    // The events_count_agent_events trigger (migration 0038) adds each
+    // insert statement's accepted rows, so a replay skipped by ON CONFLICT
+    // adds nothing, and the application never writes them. Reading them is
+    // one primary key read however many events the agent has sent. Events
+    // are append only and deleted only with their agent, so nothing ever
+    // takes one away. bigint, since an agent at the ingest cap sends
+    // millions a day.
+    eventCount: bigint('event_count', { mode: 'number' }).notNull().default(0),
+    sessionCount: bigint('session_count', { mode: 'number' })
+        .notNull()
+        .default(0),
+    toolCallCount: bigint('tool_call_count', { mode: 'number' })
+        .notNull()
+        .default(0),
+    incidentCount: bigint('incident_count', { mode: 'number' })
+        .notNull()
+        .default(0),
+    lastSeenAt: timestamp('last_seen_at', { withTimezone: true }),
     ...timestamps,
 }, (t) => [
     check('agents_id_length', sql `length(${t.id}) = 43`),

package/dist/db/client.d.ts

@@ -1,6 +1,11 @@
+import type { Logger } from 'drizzle-orm/logger';
 import postgres from 'postgres';
 export type DbOptions = {
     max?: number;
+    statementTimeoutMs?: number;
+    lockTimeoutMs?: number;
+    idleInTxTimeoutMs?: number;
+    logger?: Logger;
 };
 export declare function createDb(url: string, options?: DbOptions): import("drizzle-orm/postgres-js").PostgresJsDatabase<{
     operators: import("drizzle-orm/pg-core").PgTableWithColumns<{
@@ -492,6 +497,91 @@ export declare function createDb(url: string, options?: DbOptions): import("driz
                 identity: undefined;
                 generated: undefined;
             }, {}, {}>;
+            eventCount: import("drizzle-orm/pg-core").PgColumn<{
+                name: "event_count";
+                tableName: "agents";
+                dataType: "number";
+                columnType: "PgBigInt53";
+                data: number;
+                driverParam: string | number;
+                notNull: true;
+                hasDefault: true;
+                isPrimaryKey: false;
+                isAutoincrement: false;
+                hasRuntimeDefault: false;
+                enumValues: undefined;
+                baseColumn: never;
+                identity: undefined;
+                generated: undefined;
+            }, {}, {}>;
+            sessionCount: import("drizzle-orm/pg-core").PgColumn<{
+                name: "session_count";
+                tableName: "agents";
+                dataType: "number";
+                columnType: "PgBigInt53";
+                data: number;
+                driverParam: string | number;
+                notNull: true;
+                hasDefault: true;
+                isPrimaryKey: false;
+                isAutoincrement: false;
+                hasRuntimeDefault: false;
+                enumValues: undefined;
+                baseColumn: never;
+                identity: undefined;
+                generated: undefined;
+            }, {}, {}>;
+            toolCallCount: import("drizzle-orm/pg-core").PgColumn<{
+                name: "tool_call_count";
+                tableName: "agents";
+                dataType: "number";
+                columnType: "PgBigInt53";
+                data: number;
+                driverParam: string | number;
+                notNull: true;
+                hasDefault: true;
+                isPrimaryKey: false;
+                isAutoincrement: false;
+                hasRuntimeDefault: false;
+                enumValues: undefined;
+                baseColumn: never;
+                identity: undefined;
+                generated: undefined;
+            }, {}, {}>;
+            incidentCount: import("drizzle-orm/pg-core").PgColumn<{
+                name: "incident_count";
+                tableName: "agents";
+                dataType: "number";
+                columnType: "PgBigInt53";
+                data: number;
+                driverParam: string | number;
+                notNull: true;
+                hasDefault: true;
+                isPrimaryKey: false;
+                isAutoincrement: false;
+                hasRuntimeDefault: false;
+                enumValues: undefined;
+                baseColumn: never;
+                identity: undefined;
+                generated: undefined;
+            }, {}, {}>;
+            lastSeenAt: import("drizzle-orm/pg-core").PgColumn<{
+                name: "last_seen_at";
+                tableName: "agents";
+                dataType: "date";
+                columnType: "PgTimestamp";
+                data: Date;
+                driverParam: string;
+                notNull: false;
+                hasDefault: false;
+                isPrimaryKey: false;
+                isAutoincrement: false;
+                hasRuntimeDefault: false;
+                enumValues: undefined;
+                baseColumn: never;
+                identity: undefined;
+                generated: undefined;
+            }, {}, {}>;
         };
         dialect: 'pg';
     }>;

package/dist/db/client.js

@@ -36,5 +36,26 @@ const schema = {
 export function createDb(url, options = {}) {
     const [conn, pgOptions] = pgArgs(url);
     const max = options.max === undefined ? {} : { max: options.max };
-    return drizzle(postgres(conn, { ...pgOptions, ...max }), { schema });
+    const connection = timeoutParameters(options);
+    const logger = options.logger === undefined ? {} : { logger: options.logger };
+    return drizzle(postgres(conn, {
+        ...pgOptions,
+        ...max,
+        ...(Object.keys(connection).length > 0 ? { connection } : {}),
+    }), { schema, ...logger });
+}
+// The postgres.js connection parameters for the timeouts that are set. A
+// bare number is read by Postgres as milliseconds.
+function timeoutParameters(options) {
+    const params = {};
+    if (options.statementTimeoutMs !== undefined) {
+        params.statement_timeout = options.statementTimeoutMs;
+    }
+    if (options.lockTimeoutMs !== undefined) {
+        params.lock_timeout = options.lockTimeoutMs;
+    }
+    if (options.idleInTxTimeoutMs !== undefined) {
+        params.idle_in_transaction_session_timeout = options.idleInTxTimeoutMs;
+    }
+    return params;
 }

package/dist/db/migrator.d.ts

@@ -1,4 +1,6 @@
 export declare const migrationsFolder: string;
+export declare const MIGRATION_LOCK_TIMEOUT_MS = 5000;
+export declare const MIGRATION_STATEMENT_TIMEOUT_MS = 120000;
 export declare function runMigrations(databaseUrl: string, { onNotice }?: {
     onNotice?: (message: string) => void;
 }): Promise<void>;

package/dist/db/migrator.js

@@ -8,6 +8,12 @@ import postgres from 'postgres';
 import { pgArgs } from './url.js';
 // Resolves to packages/schema/drizzle from both src/db and dist/db.
 export const migrationsFolder = fileURLToPath(new URL('../../drizzle', import.meta.url));
+// A migration that waits on a lock, such as an ALTER TABLE queued behind the
+// scoring run's transaction, fails after MIGRATION_LOCK_TIMEOUT_MS instead of
+// waiting with no bound and blocking every query queued behind it. One
+// statement may run for MIGRATION_STATEMENT_TIMEOUT_MS (VOU-205).
+export const MIGRATION_LOCK_TIMEOUT_MS = 5_000;
+export const MIGRATION_STATEMENT_TIMEOUT_MS = 120_000;
 // onNotice receives the text of each notice a migration raises, such as
 // the operators 0025 gave a suffixed slug. Silent when left out.
 export async function runMigrations(databaseUrl, { onNotice } = {}) {
@@ -15,6 +21,10 @@ export async function runMigrations(databaseUrl, { onNotice } = {}) {
     const sql = postgres(connUrl, {
         ...options,
         max: 1,
+        connection: {
+            lock_timeout: MIGRATION_LOCK_TIMEOUT_MS,
+            statement_timeout: MIGRATION_STATEMENT_TIMEOUT_MS,
+        },
         onnotice: (notice) => onNotice?.(notice.message),
     });
     try {

package/dist/db/tasks.js

@@ -69,6 +69,12 @@ export const tasks = pgTable('tasks', {
     index('tasks_poster_agent_id_idx').on(t.posterAgentId),
     // The claim cap per claimant, activity counts, scoring and evidence.
     index('tasks_claimant_agent_id_idx').on(t.claimantAgentId),
+    // GET /v1/tasks?poster= and seed=, which is the seed agent's poster id,
+    // oldest first and paged on (posted_at, id) (VOU-208).
+    index('tasks_poster_posted_at_idx').on(t.posterAgentId, t.postedAt, t.id),
+    // GET /v1/tasks?claimant=, a CLI's own claims and submissions, oldest
+    // first and paged on (posted_at, id) (VOU-208).
+    index('tasks_claimant_posted_at_idx').on(t.claimantAgentId, t.postedAt, t.id),
     // GET /v1/tasks?state=open and the board, oldest or newest first. The
     // open pool filters out addressed tasks on top of it.
     index('tasks_open_posted_at_idx')

package/dist/index.d.ts

@@ -3,11 +3,13 @@ export * from './agent-name.js';
 export * from './api.js';
 export * from './badge.js';
 export * from './base64url.js';
+export * from './client-address.js';
 export * from './credential.js';
 export * from './dimensions.js';
 export * from './envelope.js';
 export * from './events.js';
 export * from './goal.js';
+export * from './json-shape.js';
 export * from './moderation.js';
 export * from './operator-domains.js';
 export * from './policy.js';

package/dist/index.js

@@ -3,11 +3,13 @@ export * from './agent-name.js';
 export * from './api.js';
 export * from './badge.js';
 export * from './base64url.js';
+export * from './client-address.js';
 export * from './credential.js';
 export * from './dimensions.js';
 export * from './envelope.js';
 export * from './events.js';
 export * from './goal.js';
+export * from './json-shape.js';
 export * from './moderation.js';
 export * from './operator-domains.js';
 export * from './policy.js';

package/dist/json-shape.d.ts

@@ -0,0 +1,9 @@
+import { z } from 'zod';
+export type JsonShapeLimits = {
+    readonly maxDepth: number;
+    readonly maxKeys: number;
+    readonly maxBytes: number;
+};
+export type JsonShapeIssue = 'too_deep' | 'too_many_keys';
+export declare function jsonShapeIssue(value: unknown, limits: Pick<JsonShapeLimits, 'maxDepth' | 'maxKeys'>): JsonShapeIssue | null;
+export declare function boundedJsonObject(name: string, limits: JsonShapeLimits): z.ZodRecord<z.ZodString, z.ZodUnknown>;

package/dist/json-shape.js

@@ -0,0 +1,70 @@
+import { z } from 'zod';
+import { utf8Encode } from './base64url.js';
+/*
+ * The first depth or key count limit a JSON value breaks, or null when it
+ * keeps to both.
+ *
+ * Walks with its own stack rather than recursing, so a value nested
+ * thousands deep cannot overflow the call stack, and stops at the first
+ * breach. Run it before JSON.stringify on anything a caller sent.
+ * stringify recurses and throws RangeError past about 7,700 levels, and
+ * indented output grows with the square of the depth (VOU-214).
+ */
+export function jsonShapeIssue(value, limits) {
+    const stack = [];
+    const push = (v, depth) => {
+        if (typeof v === 'object' && v !== null)
+            stack.push({ node: v, depth });
+    };
+    push(value, 1);
+    let keys = 0;
+    for (let top = stack.pop(); top !== undefined; top = stack.pop()) {
+        if (top.depth > limits.maxDepth)
+            return 'too_deep';
+        let children;
+        if (Array.isArray(top.node)) {
+            children = top.node;
+        }
+        else {
+            children = Object.values(top.node);
+            keys += children.length;
+            if (keys > limits.maxKeys)
+                return 'too_many_keys';
+        }
+        for (const child of children)
+            push(child, top.depth + 1);
+    }
+    return null;
+}
+/*
+ * A JSON object held to the limits. The depth and key checks run first, so
+ * the byte check only ever stringifies a value that cannot throw, and a
+ * breach is a Zod issue (a 400 at the API), never a RangeError (a 500).
+ * superRefine is used rather than refine so each breach gets its own
+ * message and the byte check can be skipped once one is found.
+ */
+export function boundedJsonObject(name, limits) {
+    return z.record(z.string(), z.unknown()).superRefine((value, ctx) => {
+        const issue = jsonShapeIssue(value, limits);
+        if (issue === 'too_deep') {
+            ctx.addIssue({
+                code: 'custom',
+                message: `${name} must nest at most ${limits.maxDepth} levels deep`,
+            });
+            return;
+        }
+        if (issue === 'too_many_keys') {
+            ctx.addIssue({
+                code: 'custom',
+                message: `${name} must have at most ${limits.maxKeys} keys`,
+            });
+            return;
+        }
+        if (utf8Encode(JSON.stringify(value)).length > limits.maxBytes) {
+            ctx.addIssue({
+                code: 'custom',
+                message: `${name} must be at most ${limits.maxBytes} bytes`,
+            });
+        }
+    });
+}

package/dist/moderation.d.ts

@@ -15,12 +15,13 @@ export declare const PROTECTED_PREFIXES: readonly string[];
 export declare function protectedNameOf(text: string): string | null;
 export declare const RESERVED_WORDS: readonly string[];
 export declare function isReservedWord(text: string): boolean;
-export type NameRefusalCode = 'name_protected' | 'name_reserved';
+export type NameRefusalCode = 'name_protected' | 'name_reserved' | 'name_mixed_script';
 export type NameRefusal = {
     code: NameRefusalCode;
     message: string;
 };
 export declare function moderateSlug(slug: string): NameRefusal | null;
+export declare function mixedScriptOf(text: string): string | null;
 export declare function moderateDisplayName(name: string): NameRefusal | null;
 export declare function slugBase(login: string): string;
 export declare const suffixedSlug: (base: string, n: number) => string;

package/dist/moderation.js

@@ -42,65 +42,101 @@ export const OperatorDisplayName = z
     .refine((name) => LETTER_OR_DIGIT.test(name), 'Use at least one letter or digit');
 // ---------------------------------------------------------------------------
 // Normalisation
-// Letters from other scripts that read as a Latin letter, and a few Latin
-// letters NFKD does not split into a base and a mark.
-const HOMOGLYPHS = {
-    // Cyrillic
-    а: 'a',
-    в: 'b',
-    с: 'c',
-    ԁ: 'd',
-    е: 'e',
-    ё: 'e',
-    һ: 'h',
-    н: 'h',
-    і: 'i',
-    ї: 'i',
-    ј: 'j',
-    к: 'k',
-    ӏ: 'l',
-    м: 'm',
-    п: 'n',
-    о: 'o',
-    р: 'p',
-    ԛ: 'q',
-    г: 'r',
-    ѕ: 's',
-    т: 't',
-    у: 'y',
-    ш: 'w',
-    ԝ: 'w',
-    х: 'x',
-    // Greek
-    α: 'a',
-    β: 'b',
-    ϲ: 'c',
-    ε: 'e',
-    η: 'n',
-    ι: 'i',
-    κ: 'k',
-    μ: 'u',
-    ν: 'v',
-    ο: 'o',
-    ρ: 'p',
-    τ: 't',
-    υ: 'u',
-    χ: 'x',
-    ω: 'w',
-    // Latin letters without a decomposition
-    ı: 'i',
-    ȷ: 'j',
-    ł: 'l',
-    ø: 'o',
-    đ: 'd',
-    ħ: 'h',
-    ŧ: 't',
-    ß: 'ss',
-    æ: 'ae',
-    œ: 'oe',
-    ɡ: 'g',
-    ɑ: 'a',
-    // Digits and symbols used as letters
+// Lookalikes, folded to the Latin letter they read as. Each row is a Latin
+// letter and the letters of other scripts that read as it, in the order
+// Greek, Cyrillic, Armenian, Cherokee, Canadian syllabics, Lisu, Latin,
+// Coptic, Tifinagh. The letters come from Unicode's confusables.txt, one
+// letter to one Latin letter, for these scripts only, plus the Latin small
+// capitals and a few Latin letters NFKD does not split into a base and a
+// mark. Coptic alfa and eie (Ⲁ, Ⲉ) are added by eye, they are not in the
+// list. Letters NFKC or
+// NFKD turn into another letter (the lunate sigma, the rho symbol, ё) are
+// left out, since they never reach the tables.
+function byLetter(rows) {
+    const table = {};
+    for (const [latin, lookalikes] of Object.entries(rows)) {
+        for (const ch of lookalikes) {
+            if (ch in table)
+                throw new Error(`${ch} is in two lookalike rows`);
+            table[ch] = latin;
+        }
+    }
+    return table;
+}
+// Capitals, and letters of scripts without case, that read as a Latin
+// capital. Folded before a letter is lowercased, since lowercasing first
+// would turn Greek capital Nu into nu, which reads as v, and a Cherokee
+// capital into a Cherokee small letter. So capital Nu is n here and small
+// nu is v in SMALL_LOOKALIKES.
+const CAPITAL_LOOKALIKES = byLetter({
+    a: 'ΑАᎪᗅꓮⲀ',
+    b: 'ΒВЬᏏᏴᗷꓐⲂ',
+    c: 'СᏟꓚⲤ',
+    d: 'ᎠᏧᗞᗪꓓ',
+    e: 'ΕЕᎬꓰⲈⴹ',
+    f: 'Ϝᖴꓝ',
+    g: 'ԌᏀᏳꓖ',
+    h: 'ΗНҺᎻᏂᕼꓧⲎ',
+    i: 'ΙІᎥ',
+    j: 'ͿЈᎫᒍꓙ',
+    k: 'ΚКᏦꓗⲔ',
+    l: 'ӀᏞᒪꓡꓲǀⲒⳐⵏ',
+    m: 'ΜϺМᎷᗰꓟⲘ',
+    n: 'Ν𑪾ꓠⲚ',
+    o: 'ΟОՕꓳⲞⵔ',
+    p: 'ΡРᏢᑭꓑⲢⳎ',
+    q: 'Ԛⵕ',
+    r: 'ᎡᏒᖇꓣ',
+    s: 'ЅՏᏕᏚꓢ',
+    t: 'ΤТᎢꓔⲦ',
+    u: 'Սᑌꓴ',
+    v: 'ѴᏙᐯꓦ',
+    w: 'ԜᎳᏔꓪ',
+    x: 'ΧХꓫⲬⵝ',
+    y: 'ΥУҮᎩᎽꓬ',
+    z: 'ΖᏃ𑪼ꓜ',
+});
+// Small letters that read as a Latin letter. Cherokee small letters are the
+// Cherokee capitals above, smaller, so they are added from that table.
+const SMALL_LOOKALIKES = byLetter({
+    a: 'αаɑᴀⲁ',
+    b: 'βвᑲᖯʙⲃ',
+    c: 'сᲃᴄⲥ',
+    d: 'ԁᑯꓒđᴅ',
+    e: 'εеҽᴇⲉ',
+    f: 'քꜰ',
+    g: 'ցɡɢ',
+    h: 'һнհħʜⲏ',
+    i: 'ιіꙇւıɪɩⲓ',
+    j: 'ϳјյȷᴊ',
+    k: 'κкᴋⲕ',
+    l: 'ӏłʟⳑ',
+    m: 'мᴍ',
+    n: 'ηпոռɴⲛ',
+    o: 'οоᲂօøᴏⲟϭ',
+    p: 'ρϸрᴘⲣⳏ',
+    q: 'ԛգզꞯ',
+    r: 'ᴦгʀⲅ',
+    s: 'ѕꜱ',
+    t: 'τтŧᴛⲧ',
+    u: 'μυսᴜ',
+    v: 'νѵᴠ',
+    w: 'ωшԝѡաᴡꟺⲽ',
+    x: 'χхᕁᕽⲭ',
+    y: 'уүʏⲩ',
+    z: 'ᴢ',
+    ss: 'ß',
+    ae: 'æ',
+    oe: 'œ',
+});
+for (const [ch, latin] of Object.entries(CAPITAL_LOOKALIKES)) {
+    const small = ch.toLowerCase();
+    if (small !== ch && /\p{Script=Cherokee}/u.test(ch)) {
+        SMALL_LOOKALIKES[small] = latin;
+    }
+}
+// Digits and symbols used as letters.
+const DIGIT_SWAPS = {
     '0': 'o',
     '1': 'l',
     '3': 'e',
@@ -113,20 +149,30 @@ const HOMOGLYPHS = {
     '|': 'l',
     '!': 'l',
 };
+// One letter folded. A capital by the capital it looks like, else the
+// letter lowercased and folded by the small letter it looks like.
+function foldLetter(ch) {
+    const capital = CAPITAL_LOOKALIKES[ch];
+    if (capital !== undefined)
+        return capital;
+    const small = ch.toLowerCase();
+    return SMALL_LOOKALIKES[small] ?? DIGIT_SWAPS[small] ?? small;
+}
 // i and l look alike in many fonts (GoogIe with a capital I), so both fold
-// to l. Run after HOMOGLYPHS, so a Cyrillic і, a Greek ι or a dotless ı,
-// which fold to i there, fold on to l as well.
+// to l. Run after the lookalikes, so a Cyrillic і, a Greek ι or a dotless
+// ı, which fold to i there, fold on to l as well.
 const I_AS_L = /i/g;
 const MARKS = /\p{M}/gu;
 const NOT_LETTER_OR_DIGIT = /[^\p{L}\p{N}]/gu;
-// The form two names are compared in. NFKC, lowercase, accents dropped,
-// homoglyphs and digit swaps folded, everything but letters and digits
-// dropped, then letter pairs that read as one letter (rn as m, vv as w)
-// folded. Open-AI, OPENAI and 0penai all give the same key. Letters of
-// scripts with no Latin lookalike are kept, so a display name in another
-// script still has a key of its own.
+// The form two names are compared in. NFKC, accents dropped, lookalikes of
+// other scripts and digit swaps folded by shape and the rest lowercased,
+// everything but letters and digits dropped, then letter pairs that read
+// as one letter (rn as m, vv as w) folded. Open-AI, OPENAI and 0penai all
+// give the same key, and so does OPENAI with a Greek capital Omicron.
+// Letters of scripts with no Latin lookalike are kept, so a display name
+// in another script still has a key of its own.
 export function normaliseName(text) {
-    const folded = Array.from(text.normalize('NFKC').toLowerCase().normalize('NFKD').replace(MARKS, ''), (ch) => HOMOGLYPHS[ch] ?? ch)
+    const folded = Array.from(text.normalize('NFKC').normalize('NFKD').replace(MARKS, ''), foldLetter)
         .join('')
         .replace(I_AS_L, 'l');
     return folded
@@ -403,11 +449,62 @@ export function moderateSlug(slug) {
     }
     return protectedRefusal(slug);
 }
+// Scripts a name in Latin letters may mix with, the mixes Unicode's highly
+// restrictive profile (UTS 39) allows. Han, Hiragana, Katakana, Hangul and
+// Bopomofo, plus Common and Inherited, which hold letters every script
+// shares. Any other script mixed with Latin is how a lookalike hides (Nvidia
+// with a Greek capital Nu, Google with Armenian o, OpenAI with a Coptic O),
+// so it is refused outright, whatever the tables above fold. A script not
+// listed here is refused by default, so a new lookalike script needs no row.
+// A name written in any one script alone is fine.
+const MIXES_WITH_LATIN = /[\p{Script=Latin}\p{Script=Han}\p{Script=Hiragana}\p{Script=Katakana}\p{Script=Hangul}\p{Script=Bopomofo}\p{Script=Common}\p{Script=Inherited}]/u;
+// Names for the refusal message, for the scripts with the most Latin
+// lookalikes. Any other script is "letters of another script".
+const SCRIPT_NAMES = [
+    ['Greek letters', /\p{Script=Greek}/u],
+    ['Cyrillic letters', /\p{Script=Cyrillic}/u],
+    ['Armenian letters', /\p{Script=Armenian}/u],
+    ['Cherokee letters', /\p{Script=Cherokee}/u],
+    ['Lisu letters', /\p{Script=Lisu}/u],
+    ['Canadian syllabics', /\p{Script=Canadian_Aboriginal}/u],
+    ['Coptic letters', /\p{Script=Coptic}/u],
+    ['Tifinagh letters', /\p{Script=Tifinagh}/u],
+];
+const LATIN = /\p{Script=Latin}/u;
+const LETTER = /\p{L}/u;
+// The micro sign and the ohm sign. NFKC turns them into Greek mu and
+// Omega, and the ohm sign is Greek already, so they are dropped before the
+// script check. 10kΩ Audio is a unit, not a Greek letter.
+const UNIT_SIGNS = /[\u00B5\u2126]/gu;
+// The script a text mixes with Latin letters, as the refusal names it, or
+// null when it mixes none it may not. Read after NFKC, so fullwidth and
+// styled Latin letters count as Latin.
+export function mixedScriptOf(text) {
+    const letters = Array.from(text.replace(UNIT_SIGNS, '').normalize('NFKC')).filter((ch) => LETTER.test(ch));
+    if (!letters.some((ch) => LATIN.test(ch)))
+        return null;
+    const other = letters.find((ch) => !MIXES_WITH_LATIN.test(ch));
+    if (other === undefined)
+        return null;
+    const named = SCRIPT_NAMES.find(([, pattern]) => pattern.test(other));
+    return named ? named[0] : 'letters of another script';
+}
 // The refusal for an operator display name, or null when it may be used.
-// The shape is OperatorDisplayName's job. Whether another operator holds
-// the same key is the API's check against display_name_key.
+// The shape is OperatorDisplayName's job. Protected names first, then Latin
+// mixed with a script it may not mix with. Whether another operator holds
+// the same key is the API's check against display_name_key. Slugs need no
+// script check, OperatorSlug allows a to z, digits and hyphens only.
 export function moderateDisplayName(name) {
-    return protectedRefusal(name);
+    const refusal = protectedRefusal(name);
+    if (refusal)
+        return refusal;
+    const script = mixedScriptOf(name);
+    return script === null
+        ? null
+        : {
+            code: 'name_mixed_script',
+            message: `${name} mixes Latin letters with ${script}, so it can pass for another name. Use one script.`,
+        };
 }
 // ---------------------------------------------------------------------------
 // Default slugs

package/dist/tasks.d.ts

@@ -1,6 +1,8 @@
 import { z } from 'zod';
 export declare const Sha256Hex: z.ZodString;
 export declare const JSON_SCHEMA_MAX_BYTES = 16384;
+export declare const JSON_SCHEMA_MAX_DEPTH = 20;
+export declare const JSON_SCHEMA_MAX_KEYS = 500;
 export declare const HashVerification: z.ZodObject<{
     kind: z.ZodLiteral<"hash">;
     sha256: z.ZodString;

package/dist/tasks.js

@@ -1,16 +1,26 @@
 import { z } from 'zod';
-import { utf8Encode } from './base64url.js';
+import { boundedJsonObject } from './json-shape.js';
 export const Sha256Hex = z.string().regex(/^[0-9a-f]{64}$/);
 export const JSON_SCHEMA_MAX_BYTES = 16384;
+// Depth and key caps on a jsonSchema, checked before its bytes (VOU-214).
+// The depth counts JSON levels, the top level object is 1. The API's schema
+// check allows 8 schema levels (MAX_SCHEMA_DEPTH in apps/api), and a
+// subschema under properties, allOf or an items list sits two JSON levels
+// below its parent, so an accepted schema reaches about 17. 20 refuses none
+// of them and still stops a deep bracket bomb.
+export const JSON_SCHEMA_MAX_DEPTH = 20;
+export const JSON_SCHEMA_MAX_KEYS = 500;
 export const HashVerification = z.strictObject({
     kind: z.literal('hash'),
     sha256: Sha256Hex,
 });
 export const SchemaVerification = z.strictObject({
     kind: z.literal('schema'),
-    jsonSchema: z
-        .record(z.string(), z.unknown())
-        .refine((schema) => utf8Encode(JSON.stringify(schema)).length <= JSON_SCHEMA_MAX_BYTES, `jsonSchema must be at most ${JSON_SCHEMA_MAX_BYTES} bytes`),
+    jsonSchema: boundedJsonObject('jsonSchema', {
+        maxDepth: JSON_SCHEMA_MAX_DEPTH,
+        maxKeys: JSON_SCHEMA_MAX_KEYS,
+        maxBytes: JSON_SCHEMA_MAX_BYTES,
+    }),
 });
 export const CounterpartyVerification = z.strictObject({
     kind: z.literal('counterparty'),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sealkeeper/schema",
-  "version": "0.4.5",
+  "version": "0.4.6",
   "private": false,
   "description": "Zod schemas, event taxonomy and signing helpers for SealKeeper.",
   "license": "Apache-2.0",