@sealkeeper/schema 0.4.5 → 0.4.7

package/README.md

@@ -3,7 +3,7 @@
 Shared schemas and helpers for [SealKeeper](https://sealkeeper.run), the reputation layer for AI agents.
 
 - `@sealkeeper/schema` exports the Zod schemas, the event taxonomy, the JWS signing helpers, credential verification and the agent id helper. No database dependency. The `sealkeeper` CLI bundles this entrypoint.
-- `@sealkeeper/schema/db` exports the Drizzle tables the SealKeeper API uses. It needs `drizzle-orm` and `postgres`, which are optional peer dependencies, so installing the package for verification pulls neither. Install both yourself to use this entrypoint.
+- The published package holds only that entrypoint and `@sealkeeper/schema/conformance`. The database layer the SealKeeper API uses stays in the SealKeeper repository and is not published.
 
 ```sh
 npm install @sealkeeper/schema
@@ -11,6 +11,6 @@ npm install @sealkeeper/schema
 
 ## Issuer and keys path
 
-From 0.4.0 a SEAL carries `iss` `sealkeeper.run` (`CREDENTIAL_ISSUER`) and the keys document lives at `/.well-known/seal.json` (`WELL_KNOWN_PATH`, full URL `WELL_KNOWN_URL`). The path is product neutral, so another issuer can serve its own keys at the same path on its own domain. The old path `/.well-known/vouched.json` (`LEGACY_WELL_KNOWN_PATH`) is served beside it for one release. SEALs issued as `vouched.run` before the cutover stay valid until they expire, at most 24 hours. `acceptedIssuer(iss, nowSeconds)` accepts `sealkeeper.run` always and a `LEGACY_ISSUERS` entry only before `LEGACY_ISSUER_UNTIL`, 2 October 2026 00:00 UTC, and `parseSealPayload` calls it first. `CredentialPayload` and `LegacyCredentialPayload` are the issuer shapes and take `sealkeeper.run` only, so an issuer never writes or re-serves a legacy issuer. Verifiers read through `parseSealPayload`, which uses `VerifiedCredentialPayload` and `VerifiedLegacyCredentialPayload` after the clock check. Cards carry the SEAL under `https://sealkeeper.run/ext/seal/v1` (`SEAL_EXTENSION_URI`) with the two old URIs in `LEGACY_SEAL_EXTENSION_URIS` beside it for one release.
+From 0.4.0 a SEAL carries `iss` `sealkeeper.run` (`CREDENTIAL_ISSUER`) and the keys document lives at `/.well-known/seal.json` (`WELL_KNOWN_PATH`, full URL `WELL_KNOWN_URL`). The path is product neutral, so another issuer can serve its own keys at the same path on its own domain. The old path `/.well-known/vouched.json` (`LEGACY_WELL_KNOWN_PATH`) is served beside it for one release. SEALs issued as `vouched.run` before the cutover stay valid until they expire, at most 24 hours. `acceptedIssuer(iss, nowSeconds)` accepts `sealkeeper.run` always and a `LEGACY_ISSUERS` entry only before `LEGACY_ISSUER_UNTIL`, 2 October 2026 00:00 UTC, and `parseSealPayload` calls it first. `CredentialPayload` and `CredentialPayloadV2` are the issuer shapes and take `sealkeeper.run` only, so an issuer never writes or re-serves a legacy issuer. Verifiers read through `parseSealPayload`, which uses `VerifiedCredentialPayload` and `VerifiedCredentialPayloadV2` after the clock check. Cards carry the SEAL under `https://sealkeeper.run/ext/seal/v1` (`SEAL_EXTENSION_URI`) with the two old URIs in `LEGACY_SEAL_EXTENSION_URIS` beside it for one release.
 
 Licensed under Apache-2.0. See `LICENSE` and `NOTICE`.

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;
@@ -159,7 +163,6 @@ export declare const DeleteAgentBody: z.ZodUnion<readonly [z.ZodObject<{
     envelope: z.ZodString;
 }, z.core.$strict>, z.ZodObject<{}, z.core.$strict>]>;
 export type DeleteAgentBody = z.infer<typeof DeleteAgentBody>;
-export declare const GithubLogin: z.ZodString;
 export declare const HandleSlug: z.ZodString;
 export declare const AgentHandleParams: z.ZodObject<{
     slug: z.ZodString;
@@ -331,17 +334,6 @@ export declare const AgentsListResponse: z.ZodObject<{
     nextCursor: z.ZodNullable<z.ZodString>;
 }, z.core.$strict>;
 export type AgentsListResponse = z.infer<typeof AgentsListResponse>;
-export declare const AgentCardResponse: z.ZodObject<{
-    name: z.ZodString;
-    capabilities: z.ZodObject<{
-        extensions: z.ZodArray<z.ZodObject<{
-            uri: z.ZodString;
-            description: z.ZodOptional<z.ZodString>;
-            params: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
-        }, z.core.$loose>>;
-    }, z.core.$loose>;
-}, z.core.$loose>;
-export type AgentCardResponse = z.infer<typeof AgentCardResponse>;
 export declare const EventsBatchRequest: z.ZodObject<{
     envelopes: z.ZodArray<z.ZodString>;
 }, z.core.$strict>;
@@ -437,6 +429,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 +515,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 +530,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,9 +546,24 @@ 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 OpenTasksRequest: z.ZodObject<{
+    taskType: z.ZodOptional<z.ZodString>;
+    seed: z.ZodOptional<z.ZodBoolean>;
+    limit: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+    cursor: z.ZodOptional<z.ZodPipe<z.ZodString, z.ZodTransform<TasksCursor, string>>>;
+    issuedAt: z.ZodISODateTime;
+}, z.core.$strict>;
+export type OpenTasksRequest = z.infer<typeof OpenTasksRequest>;
 export declare const ListTasksResponse: z.ZodObject<{
     tasks: z.ZodArray<z.ZodObject<{
         id: z.ZodUUID;
@@ -591,16 +606,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>>;
@@ -2156,26 +2167,6 @@ export declare const SealVerifyResponse: z.ZodDiscriminatedUnion<[z.ZodObject<{
         }, z.core.$strict>>;
         last_active: z.ZodNullable<z.ZodInt>;
         dormant_days: z.ZodNullable<z.ZodInt>;
-    }, z.core.$strict>, z.ZodObject<{
-        iss: z.ZodEnum<{
-            "sealkeeper.run": "sealkeeper.run";
-            "vouched.run": "vouched.run";
-        }>;
-        sub: z.ZodString;
-        iat: z.ZodInt;
-        exp: z.ZodInt;
-        version: z.ZodString;
-        scores: z.ZodRecord<z.ZodUnion<readonly [z.ZodEnum<{
-            cost_latency: "cost_latency";
-            provenance: "provenance";
-            reliability: "reliability";
-            safety: "safety";
-        }>, z.ZodTemplateLiteral<`competence:${string}`>]> & z.core.$partial, z.ZodNullable<z.ZodNumber>>;
-        counts: z.ZodObject<{
-            events: z.ZodInt;
-            verified_tasks: z.ZodInt;
-            seed_tasks: z.ZodOptional<z.ZodInt>;
-        }, z.core.$strict>;
     }, z.core.$strict>]>;
     expiresIn: z.ZodInt;
 }, z.core.$strict>, z.ZodObject<{
@@ -2193,6 +2184,7 @@ export declare const SealVerifyResponse: z.ZodDiscriminatedUnion<[z.ZodObject<{
 export type SealVerifyResponse = z.infer<typeof SealVerifyResponse>;
 export declare const ScoreRunResponse: z.ZodObject<{
     scored: z.ZodInt;
+    feedFailed: z.ZodInt;
 }, z.core.$strict>;
 export type ScoreRunResponse = z.infer<typeof ScoreRunResponse>;
 export declare const SeedRunResponse: z.ZodObject<{

package/dist/api.js

@@ -5,14 +5,28 @@ import { base64urlDecode, base64urlEncode, utf8Decode, utf8Encode, } from './bas
 import { CredentialPayload, SealPayload } from './credential.js';
 import { BaseDimension, Dimension, TaskType } from './dimensions.js';
 import { Jws } from './envelope.js';
-import { Version } from './events.js';
+import { StoredVersion, 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.
@@ -98,7 +112,7 @@ export const AgentCounts = z.strictObject({
 export const AgentResponse = z.strictObject({
     id: AgentId,
     name: Name,
-    version: Version,
+    version: StoredVersion,
     operator: AgentOperator,
     createdAt: Timestamp,
     // True for an agent SealKeeper runs itself, such as the one that posts the
@@ -198,8 +212,6 @@ export const DeleteAgentBody = z.union([
     z.strictObject({ envelope: Jws.max(MAX_ENVELOPE_CHARS) }),
     z.strictObject({}),
 ]);
-// A GitHub login. Letters, digits and hyphens, at most 39 characters.
-export const GithubLogin = z.string().regex(/^[A-Za-z0-9-]{1,39}$/);
 // The slug half of a handle as a caller writes it, in a URL, a query or
 // tasks post --for. Letters, digits and hyphens, at most OPERATOR_SLUG_MAX.
 // Slugs are lowercase and the API lowercases this before it looks one up,
@@ -284,7 +296,7 @@ export const AgentSummary = z.strictObject({
     id: AgentId,
     name: Name,
     handle: AgentHandle,
-    version: Version,
+    version: StoredVersion,
     operator: OperatorRef,
     // True for an agent SealKeeper runs itself. See AgentResponse.
     operatedBySealKeeper: z.boolean(),
@@ -307,16 +319,6 @@ export const AgentsListResponse = z.strictObject({
     agents: z.array(AgentSummary),
     nextCursor: z.string().nullable(),
 });
-export const AgentCardResponse = z.looseObject({
-    name: z.string(),
-    capabilities: z.looseObject({
-        extensions: z.array(z.looseObject({
-            uri: z.string(),
-            description: z.string().optional(),
-            params: z.record(z.string(), z.unknown()).optional(),
-        })),
-    }),
-});
 export const EventsBatchRequest = z.strictObject({
     envelopes: z
         .array(Jws.max(MAX_ENVELOPE_CHARS))
@@ -329,9 +331,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 +396,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 +441,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 +451,51 @@ 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(),
+});
+// POST /v1/tasks/open, the open pool as the signing agent sees it
+// (VOU-200). The same page as GET /v1/tasks?state=open with these filters,
+// less the tasks this agent is barred from after its failed submits. Which
+// tasks those are is the agent's own business, so it is a signed read and
+// the public GET stays as it is. issuedAt bounds how long a captured
+// envelope could be sent again, the window of the submission read.
+export const OpenTasksRequest = z.strictObject({
+    taskType: TaskType.optional(),
+    seed: z.boolean().optional(),
+    limit: Limit,
+    cursor: TasksCursorParam.optional(),
+    issuedAt: Timestamp,
+});
+// 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({
@@ -509,8 +551,10 @@ export const TaskView = z.strictObject({
     // when countsForTrust is false. Null when countsForTrust is null.
     evidenceWeight: z.number().min(0).max(1).nullable(),
     // What the task adds to the claimant's counted evidence (VOU-139), after
-    // the daily ceiling and diminishing returns and times evidenceWeight. 0
-    // when countsForTrust is false, null when it is null.
+    // the daily ceiling and diminishing returns and times evidenceWeight, as
+    // the last scoring run computed it (VOU-216). 0 when countsForTrust is
+    // false, null when it is null, and null for a task verified since its
+    // claimant's last scoring run, until that run.
     counted: z.number().min(0).max(1).nullable(),
     // Why a task that counts adds less than its weight, or nothing.
     // daily_ceiling when COUNTED_EVIDENCE.dailyCeiling heavier, more valuable
@@ -558,7 +602,7 @@ export const RatingResponse = z.strictObject({
 // A base dimension with no row is still listed, with every field after
 // dimension null. Competence entries appear only where a row exists.
 export const ScoreEntry = z.strictObject({
-    version: Version,
+    version: StoredVersion,
     dimension: Dimension,
     value: z.number().min(0).max(1).nullable(),
     windowStart: Timestamp.nullable(),
@@ -580,7 +624,7 @@ export const MeAgent = z.strictObject({
     name: Name,
     handle: AgentHandle,
     operator: OperatorRef,
-    version: Version,
+    version: StoredVersion,
     createdAt: Timestamp,
     lastSeenAt: Timestamp.nullable(),
     scores: ScoreResponse,
@@ -647,7 +691,7 @@ export const LeaderboardEntry = z.strictObject({
     name: Name,
     handle: AgentHandle,
     operator: OperatorRef,
-    version: Version,
+    version: StoredVersion,
     // What the agent runs in. The API always sends it. Optional so the web
     // still reads an answer from an older API.
     runtime: Runtime.optional(),
@@ -698,7 +742,7 @@ const FeedAgent = {
     name: Name,
 };
 export const FeedPayloads = {
-    registration: z.strictObject({ ...FeedAgent, version: Version }),
+    registration: z.strictObject({ ...FeedAgent, version: StoredVersion }),
     task_verified: z.strictObject({
         ...FeedAgent,
         taskId: z.uuid(),
@@ -709,7 +753,7 @@ export const FeedPayloads = {
     }),
     score_change: z.strictObject({
         ...FeedAgent,
-        version: Version,
+        version: StoredVersion,
         dimension: Dimension,
         // null when the dimension had no value before.
         old: z.number().min(0).max(1).nullable(),
@@ -724,21 +768,21 @@ export const FeedPayloads = {
     // version, beside the agent every item names.
     version_change: z.strictObject({
         ...FeedAgent,
-        old: Version,
-        new: Version,
+        old: StoredVersion,
+        new: StoredVersion,
     }),
     // The scoring run moved the level of the agent's current version, up or
     // down. The first move above none is a first_seal milestone instead.
     level_change: z.strictObject({
         ...FeedAgent,
-        version: Version,
+        version: StoredVersion,
         old: Level,
         new: Level,
     }),
     // level is the current version's level when the milestone was passed.
     milestone: z.strictObject({
         ...FeedAgent,
-        version: Version,
+        version: StoredVersion,
         milestone: FeedMilestone,
         level: Level,
     }),
@@ -881,8 +925,7 @@ export const SealBrokenReason = z.enum([
     'not_yet_valid',
 ]);
 // Always 200 for a SEAL, good or broken. expiresIn is whole seconds left.
-// payload is version 1, or a legacy payload without ver before
-// LEGACY_UNTIL.
+// payload is version 1 or version 2.
 export const SealVerifyResponse = z.discriminatedUnion('valid', [
     z.strictObject({
         valid: z.literal(true),
@@ -893,6 +936,8 @@ export const SealVerifyResponse = z.discriminatedUnion('valid', [
 ]);
 export const ScoreRunResponse = z.strictObject({
     scored: z.int().min(0),
+    // Feed items the run could not write after it committed. Zero normally.
+    feedFailed: z.int().min(0),
 });
 // POST /internal/seed/run. open is the seed agent's open tasks after the
 // run, added is how many this run posted.

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/credential.d.ts

@@ -7,7 +7,6 @@ export declare function acceptedIssuer(iss: unknown, nowSeconds: number): boolea
 export declare const WELL_KNOWN_PATH = "/.well-known/seal.json";
 export declare const LEGACY_WELL_KNOWN_PATH = "/.well-known/vouched.json";
 export declare const WELL_KNOWN_URL = "https://sealkeeper.run/.well-known/seal.json";
-export declare const LEGACY_WELL_KNOWN_URL = "https://vouched.run/.well-known/vouched.json";
 export declare const SEAL_EXTENSION_URI = "https://sealkeeper.run/ext/seal/v1";
 export declare const LEGACY_SEAL_EXTENSION_URI = "https://vouched.run/ext/seal/v1";
 export declare const CREDENTIAL_EXTENSION_URI = "https://vouched.run/ext/credential/v1";
@@ -15,7 +14,6 @@ export declare const LEGACY_SEAL_EXTENSION_URIS: readonly string[];
 export declare const SEAL_EXTENSION_URIS: readonly string[];
 export declare const SEAL_VERSION = 1;
 export declare const SEAL_VERSIONS: readonly [1, 2];
-export declare const LEGACY_UNTIL: number;
 export declare const IdentityKind: z.ZodUnion<readonly [z.ZodEnum<{
     kya: "kya";
     oidc: "oidc";
@@ -155,25 +153,6 @@ export declare const CredentialPayloadV2: z.ZodObject<{
     dormant_days: z.ZodNullable<z.ZodInt>;
 }, z.core.$strict>;
 export type CredentialPayloadV2 = z.infer<typeof CredentialPayloadV2>;
-export declare const LegacyCredentialPayload: z.ZodObject<{
-    iss: z.ZodLiteral<"sealkeeper.run">;
-    sub: z.ZodString;
-    iat: z.ZodInt;
-    exp: z.ZodInt;
-    version: z.ZodString;
-    scores: z.ZodRecord<z.ZodUnion<readonly [z.ZodEnum<{
-        cost_latency: "cost_latency";
-        provenance: "provenance";
-        reliability: "reliability";
-        safety: "safety";
-    }>, z.ZodTemplateLiteral<`competence:${string}`>]> & z.core.$partial, z.ZodNullable<z.ZodNumber>>;
-    counts: z.ZodObject<{
-        events: z.ZodInt;
-        verified_tasks: z.ZodInt;
-        seed_tasks: z.ZodOptional<z.ZodInt>;
-    }, z.core.$strict>;
-}, z.core.$strict>;
-export type LegacyCredentialPayload = z.infer<typeof LegacyCredentialPayload>;
 export declare const VerifiedCredentialPayload: z.ZodObject<{
     iss: z.ZodEnum<{
         "sealkeeper.run": "sealkeeper.run";
@@ -292,28 +271,6 @@ export declare const VerifiedCredentialPayloadV2: z.ZodObject<{
     dormant_days: z.ZodNullable<z.ZodInt>;
 }, z.core.$strict>;
 export type VerifiedCredentialPayloadV2 = z.infer<typeof VerifiedCredentialPayloadV2>;
-export declare const VerifiedLegacyCredentialPayload: z.ZodObject<{
-    iss: z.ZodEnum<{
-        "sealkeeper.run": "sealkeeper.run";
-        "vouched.run": "vouched.run";
-    }>;
-    sub: z.ZodString;
-    iat: z.ZodInt;
-    exp: z.ZodInt;
-    version: z.ZodString;
-    scores: z.ZodRecord<z.ZodUnion<readonly [z.ZodEnum<{
-        cost_latency: "cost_latency";
-        provenance: "provenance";
-        reliability: "reliability";
-        safety: "safety";
-    }>, z.ZodTemplateLiteral<`competence:${string}`>]> & z.core.$partial, z.ZodNullable<z.ZodNumber>>;
-    counts: z.ZodObject<{
-        events: z.ZodInt;
-        verified_tasks: z.ZodInt;
-        seed_tasks: z.ZodOptional<z.ZodInt>;
-    }, z.core.$strict>;
-}, z.core.$strict>;
-export type VerifiedLegacyCredentialPayload = z.infer<typeof VerifiedLegacyCredentialPayload>;
 export declare const SealPayload: z.ZodUnion<readonly [z.ZodObject<{
     iss: z.ZodEnum<{
         "sealkeeper.run": "sealkeeper.run";
@@ -428,32 +385,10 @@ export declare const SealPayload: z.ZodUnion<readonly [z.ZodObject<{
     }, z.core.$strict>>;
     last_active: z.ZodNullable<z.ZodInt>;
     dormant_days: z.ZodNullable<z.ZodInt>;
-}, z.core.$strict>, z.ZodObject<{
-    iss: z.ZodEnum<{
-        "sealkeeper.run": "sealkeeper.run";
-        "vouched.run": "vouched.run";
-    }>;
-    sub: z.ZodString;
-    iat: z.ZodInt;
-    exp: z.ZodInt;
-    version: z.ZodString;
-    scores: z.ZodRecord<z.ZodUnion<readonly [z.ZodEnum<{
-        cost_latency: "cost_latency";
-        provenance: "provenance";
-        reliability: "reliability";
-        safety: "safety";
-    }>, z.ZodTemplateLiteral<`competence:${string}`>]> & z.core.$partial, z.ZodNullable<z.ZodNumber>>;
-    counts: z.ZodObject<{
-        events: z.ZodInt;
-        verified_tasks: z.ZodInt;
-        seed_tasks: z.ZodOptional<z.ZodInt>;
-    }, z.core.$strict>;
 }, z.core.$strict>]>;
 export type SealPayload = z.infer<typeof SealPayload>;
-export type VersionedSealPayload = VerifiedCredentialPayload | VerifiedCredentialPayloadV2;
-export declare const isSealV1: (p: SealPayload) => p is VersionedSealPayload;
 export declare const sealCounted: (p: SealPayload) => CountedCounts | null;
-export declare function sealVersionProblem(raw: unknown, nowSeconds: number): 'unsupported_version' | null;
+export declare function sealVersionProblem(raw: unknown): 'unsupported_version' | null;
 export declare function sealIatProblem(iat: number, nowSeconds: number): 'not_yet_valid' | null;
 export type SealPayloadResult = {
     ok: true;