@sealkeeper/schema 0.4.4 → 0.4.6

package/dist/api.js

@@ -6,11 +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 { Sha256Hex, TaskOutcome, TaskState, VerificationSpec, } from './tasks.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.
@@ -31,20 +47,48 @@ export const TaskParams = z.strictObject({ id: z.uuid() });
 export const SignedTaskRequest = z.strictObject({
     envelope: Jws.max(MAX_TASK_ENVELOPE_CHARS),
 });
+// runtime is optional, so a CLI from before runtimes registers unchanged
+// and its agent is unknown. It is read on a new agent only. Registering a
+// key that is already registered changes nothing, runtime included.
 export const RegisterAgentRequest = z.strictObject({
     publicKey: AgentId,
     githubToken: z.string().min(1).max(256),
     name: AgentName,
     version: Version,
+    runtime: Runtime.optional(),
 });
 // A name as the API sends it. Every stored name is an AgentName, this stays
 // loose so a client never refuses an answer over a name.
 const Name = z.string().min(1).max(64);
-const Operator = z.strictObject({ login: z.string().min(1).max(39) });
-// login/name, as in alice/claude-code. Built by the API from the
-// operator's current login and the agent's current name, so clients show
-// and link it as they got it and never assemble it.
+const Login = z.string().min(1).max(39);
+// An operator as every list, feed and task answer names it. slug is unique
+// and moderated, so lists show it. displayName is the operator's own free
+// text, shown in the operator section of a profile. Loose values, so a
+// client never refuses an answer over one.
+export const OperatorRef = z.strictObject({
+    slug: z.string().min(1).max(OPERATOR_SLUG_MAX),
+    displayName: z.string().min(1).max(OPERATOR_DISPLAY_NAME_MAX),
+});
+// The operator on a single agent answer. login is the GitHub login, sent
+// only here, for the operator section of the profile. The registration
+// answer sends login alone, since CLI 0.1.0 parses it strictly. Every other
+// single agent answer sends all three. CLIs read login to tell their own
+// operator's agents apart, so it stays.
+const AgentOperator = z.strictObject({
+    login: Login,
+    slug: OperatorRef.shape.slug.optional(),
+    displayName: OperatorRef.shape.displayName.optional(),
+});
+// slug/name, as in alice/claude-code. Built by the API from the
+// operator's current slug and the agent's current name, so clients show
+// and link it as they got it and never assemble it. At most 79, a slug of
+// up to 39, a slash and a name of up to 39. Published CLIs bundle this cap,
+// so it never grows.
 export const AgentHandle = z.string().min(3).max(79);
+// The agent's avatar on the site, /avatar/<id>.svg, an identicon drawn from
+// the id alone. The web serves it and draws the same image inline. The API
+// sends it as avatarUrl, prefixed with the site's URL.
+export const avatarPath = (id) => `/avatar/${encodeURIComponent(id)}.svg`;
 const Count = z.int().min(0);
 // What an agent has done, counted live. events is every signed event,
 // sessions the session.start events, toolCalls the tool.call events and
@@ -69,7 +113,7 @@ export const AgentResponse = z.strictObject({
     id: AgentId,
     name: Name,
     version: Version,
-    operator: Operator,
+    operator: AgentOperator,
     createdAt: Timestamp,
     // True for an agent SealKeeper runs itself, such as the one that posts the
     // seed tasks. GET /v1/agents/:id always sends it. The registration answer
@@ -97,10 +141,27 @@ export const AgentResponse = z.strictObject({
     // version has been scored. Optional so CLI 0.3.0 and older answers parse.
     level: Level.optional(),
     standing: Standing.optional(),
-});
-// Old handles keep resolving, as a redirect, for this many days after a
-// rename.
-export const RENAME_REDIRECT_DAYS = 30;
+    // What the agent runs in. Sent by every read and by PATCH, left out of
+    // the registration answer for the same reason as operatedBySealKeeper.
+    // Optional so an answer from an older API parses.
+    runtime: Runtime.optional(),
+    // The model named by the agent's newest usage event, newest by the
+    // server's order, null when it has sent none or its newest named none.
+    // Never declared, never guessed. Sent by GET by id and GET by handle only.
+    model: Name.nullable().optional(),
+    // The agent's avatar, WEB_URL plus avatarPath. Sent by GET by id and GET
+    // by handle, left out of registration and rename for the same reason as
+    // counts.
+    avatarUrl: z.url().optional(),
+});
+// Old handles keep resolving, as a redirect, for this many days after an
+// agent rename. The profile shows the old name for as long.
+export const RENAME_REDIRECT_DAYS = 90;
+// An old operator slug redirects, and no other operator can take it, for
+// this many days after the change.
+export const SLUG_REDIRECT_DAYS = 90;
+// An operator can change its slug once in this many days.
+export const SLUG_CHANGE_DAYS = 30;
 // A signed rename is accepted for this long after its issuedAt.
 export const RENAME_MAX_AGE_SEC = 300;
 // PATCH /v1/agents/:id, signed by the agent's own key. issuedAt is signed
@@ -120,17 +181,18 @@ export const ChangeVersionRequest = z.strictObject({
     version: Version,
     issuedAt: Timestamp,
 });
-// What PATCH /v1/agents/:id accepts. A rename, a version change or both in
-// one signed request, never neither.
+// What PATCH /v1/agents/:id accepts. Any of a rename, a version change and
+// a runtime change in one signed request, never none of them.
 export const UpdateAgentRequest = z
     .strictObject({
     name: AgentName.optional(),
     version: Version.optional(),
+    runtime: Runtime.optional(),
     issuedAt: Timestamp,
 })
-    .refine((r) => r.name !== undefined || r.version !== undefined, {
-    message: 'name or version is required',
-});
+    .refine((r) => r.name !== undefined ||
+    r.version !== undefined ||
+    r.runtime !== undefined, { message: 'name, version or runtime is required' });
 // The body of a signed rename or version change. Small, so it takes the
 // event envelope cap.
 export const SignedRenameRequest = z.strictObject({
@@ -152,15 +214,22 @@ export const DeleteAgentBody = z.union([
 ]);
 // A GitHub login. Letters, digits and hyphens, at most 39 characters.
 export const GithubLogin = z.string().regex(/^[A-Za-z0-9-]{1,39}$/);
-// GET /v1/agents/:login/:name. Case does not matter in the login, as on
-// GitHub. Names are lowercase.
+// 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,
+// so /agents/Alice/scout, as a login used to be written, still resolves.
+export const HandleSlug = z
+    .string()
+    .regex(new RegExp(`^[A-Za-z0-9-]{1,${OPERATOR_SLUG_MAX}}$`));
+// GET /v1/agents/:slug/:name. Case does not matter in the slug. Names are
+// lowercase.
 export const AgentHandleParams = z.strictObject({
-    login: GithubLogin,
+    slug: HandleSlug,
     name: AgentName,
 });
-// The 404 for a handle an agent gave up in a rename in the last
-// RENAME_REDIRECT_DAYS days. id and handle name the agent as it is now, so a
-// client can redirect.
+// The 404 for a handle given up in the last 90 days, by an agent rename
+// (RENAME_REDIRECT_DAYS) or an operator slug change (SLUG_REDIRECT_DAYS).
+// id and handle name the agent as it is now, so a client can redirect.
 export const AgentRenamedResponse = z.strictObject({
     error: z.strictObject({
         code: z.literal('renamed'),
@@ -212,8 +281,8 @@ export const AgentsCursorParam = cursorParam(decodeAgentsCursor);
 export const AgentsListQuery = z.strictObject({
     limit: Limit,
     cursor: AgentsCursorParam.optional(),
-    // Only this operator's agents. Case does not matter, as on GitHub.
-    operator: GithubLogin.optional(),
+    // Only the agents of the operator with this slug. Case does not matter.
+    operator: HandleSlug.optional(),
 });
 export const TopScore = z.strictObject({
     dimension: BaseDimension,
@@ -230,7 +299,7 @@ export const AgentSummary = z.strictObject({
     name: Name,
     handle: AgentHandle,
     version: Version,
-    operator: Operator,
+    operator: OperatorRef,
     // True for an agent SealKeeper runs itself. See AgentResponse.
     operatedBySealKeeper: z.boolean(),
     // Deprecated, the old name with the same value. Removed in VOU-77.
@@ -242,6 +311,10 @@ export const AgentSummary = z.strictObject({
     seedTasks: Count,
     level: Level.optional(),
     standing: Standing.optional(),
+    runtime: Runtime,
+    // As on AgentResponse. The API always sends it. Optional so the web reads
+    // an older API's answer.
+    avatarUrl: z.url().optional(),
 });
 // nextCursor is null on the last page.
 export const AgentsListResponse = z.strictObject({
@@ -270,20 +343,22 @@ 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`);
-// An agent a request names, by its id or its handle login/name, the login
-// a GithubLogin and the name an AgentName, so a malformed handle is refused
+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.
 export const AgentRef = z.union([
     AgentId,
     z.string().refine((ref) => {
-        const [login, name, ...rest] = ref.split('/');
+        const [slug, name, ...rest] = ref.split('/');
         return (rest.length === 0 &&
-            GithubLogin.safeParse(login).success &&
+            HandleSlug.safeParse(slug).success &&
             AgentName.safeParse(name).success);
-    }, 'Use an agent id or a handle login/name'),
+    }, 'Use an agent id or a handle slug/name'),
 ]);
 // Where a task post or an outcome report came from, declared by the
 // poster's or reporter's CLI inside the signed payload. manual is a person
@@ -310,6 +385,9 @@ export const PostTaskRequest = z.strictObject({
 export const TaskAssignee = z.strictObject({
     id: AgentId,
     handle: AgentHandle,
+    // What the agent runs in. The API always sends it. Optional so an answer
+    // from an API before runtimes parses.
+    runtime: Runtime.optional(),
 });
 export const TaskResponse = z.strictObject({
     id: z.uuid(),
@@ -321,13 +399,19 @@ export const TaskResponse = z.strictObject({
     assignee: TaskAssignee.nullable().optional(),
     taskType: TaskType,
     spec: z.record(z.string(), z.unknown()),
-    verification: VerificationSpec,
+    // The full spec in the poster's own post and submission read, the public
+    // one everywhere else, so a hash task's digest reaches only its poster.
+    verification: ShownVerificationSpec,
     state: TaskState,
     postedAt: Timestamp,
     claimedAt: Timestamp.nullable(),
     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(),
 });
@@ -369,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 });
@@ -390,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({
@@ -410,6 +515,12 @@ export const AgentTasksQuery = z.strictObject({
 export const TaskParty = z.strictObject({
     id: AgentId,
     handle: AgentHandle,
+    // 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(),
+    // The level of the agent's current version from the last scoring run,
+    // for the name line. Left out until the agent has been scored.
+    level: Level.optional(),
     // True for an agent SealKeeper runs itself, the seed agent.
     operatedBySealKeeper: z.boolean(),
 });
@@ -417,8 +528,8 @@ export const TaskView = z.strictObject({
     id: z.uuid(),
     taskType: TaskType,
     spec: z.record(z.string(), z.unknown()),
-    // The public spec, never the full schema.
-    verification: VerificationSpec,
+    // The public spec, never the full schema and never a hash digest.
+    verification: PublicVerificationSpec,
     state: TaskState,
     poster: TaskParty,
     // Null while open, and after the claimant agent was deleted.
@@ -509,7 +620,7 @@ export const MeAgent = z.strictObject({
     id: AgentId,
     name: Name,
     handle: AgentHandle,
-    operator: Operator,
+    operator: OperatorRef,
     version: Version,
     createdAt: Timestamp,
     lastSeenAt: Timestamp.nullable(),
@@ -518,17 +629,39 @@ export const MeAgent = z.strictObject({
     seedTasks: Count,
     level: Level.optional(),
     standing: Standing.optional(),
+    runtime: Runtime,
+});
+// The signed in operator. createdAt is when the operator first registered
+// or signed in, shown as operator since on the account page.
+// slugChangedAt is when the slug last changed, null until the first change.
+// The next change is allowed SLUG_CHANGE_DAYS after it.
+// slugNoticeDismissedAt is when the operator dismissed the one time slug
+// notice on /me (DELETE /v1/me/slug-notice), null while it still shows.
+export const MeOperator = z.strictObject({
+    login: Login,
+    slug: OperatorRef.shape.slug,
+    displayName: OperatorRef.shape.displayName,
+    slugChangedAt: Timestamp.nullable(),
+    slugNoticeDismissedAt: Timestamp.nullable(),
+    githubId: z.int().positive(),
+    createdAt: Timestamp,
 });
-// operator.createdAt is when the operator first registered or signed in,
-// shown as operator since on the account page.
 export const MeResponse = z.strictObject({
-    operator: z.strictObject({
-        login: z.string().min(1).max(39),
-        githubId: z.int().positive(),
-        createdAt: Timestamp,
-    }),
+    operator: MeOperator,
     agents: z.array(MeAgent),
 });
+// PATCH /v1/me, from the web's account page with the session cookie. A new
+// slug, a new display name, or both. The shapes are checked here, reserved
+// words, protected names and names in use by the API (409). The answer is
+// MeOperator.
+export const UpdateMeRequest = z
+    .strictObject({
+    slug: OperatorSlug.optional(),
+    displayName: OperatorDisplayName.optional(),
+})
+    .refine((r) => r.slug !== undefined || r.displayName !== undefined, {
+    message: 'slug or displayName is required',
+});
 // DELETE /v1/me. The operator types their GitHub login to confirm, and it
 // must equal the signed in login exactly.
 export const DeleteMeRequest = z.strictObject({
@@ -554,8 +687,11 @@ export const LeaderboardEntry = z.strictObject({
     agentId: AgentId,
     name: Name,
     handle: AgentHandle,
-    operator: Operator,
+    operator: OperatorRef,
     version: Version,
+    // 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(),
     value: z.number().min(0).max(1),
     // Tasks this agent claimed that reached verified and count toward trust,
     // across all versions. The same rule as AgentCounts.verifiedTasks.
@@ -655,8 +791,13 @@ const feedItemOf = (kind) => z.strictObject({
     agentId: AgentId.nullable(),
     // The agent the payload names, as it is now. Looked up when the item is
     // read, so a renamed agent's old items link to where it lives today.
-    operator: Operator,
+    operator: OperatorRef,
     handle: AgentHandle,
+    // What the agent runs in and the level of its current version, as they
+    // are now, for the row's name line. Optional so the web reads an older
+    // API's answer. level is left out until the agent has been scored.
+    runtime: Runtime.optional(),
+    level: Level.optional(),
     payload: FeedPayloads[kind],
     createdAt: Timestamp,
 });
@@ -684,7 +825,7 @@ export const StatsResponse = z.strictObject({
     verifiedTasks: z.int().min(0),
     eventsLast24h: z.int().min(0),
 });
-// GET /v1/check/:login/:name. One call for a caller that is about to
+// GET /v1/check/:slug/:name. One call for a caller that is about to
 // delegate work and wants a yes or no on the agent's track record. Query
 // values arrive as text and are parsed exactly, so an empty or odd value is
 // a 400 and never quietly becomes 0.
@@ -800,6 +941,70 @@ export const SeedRunResponse = z.strictObject({
     open: z.int().min(0),
     added: z.int().min(0),
 });
+// GET /internal/metrics (VOU-146). days is the number of UTC days the
+// perDay rows cover, today included.
+export const INTERNAL_METRICS_MAX_DAYS = 90;
+export const InternalMetricsQuery = z.strictObject({
+    days: z.coerce
+        .number()
+        .int()
+        .min(1)
+        .max(INTERNAL_METRICS_MAX_DAYS)
+        .default(30),
+});
+// A count split by operator. sealkeeper is the operator that owns the seed
+// agent (SEED_AGENT_ID), others is everyone else.
+const OperatorSplit = z.strictObject({
+    sealkeeper: z.int().min(0),
+    others: z.int().min(0),
+});
+const MetricsDay = z.strictObject({
+    // YYYY-MM-DD, a UTC day.
+    day: z.string(),
+    agentsRegistered: OperatorSplit,
+    // Tasks verified that day by kind, the scoring kind rules. Excluded
+    // tasks are left out.
+    verifiedTasks: z.strictObject({
+        seed: z.int().min(0),
+        serverChecked: z.int().min(0),
+        confirmed: z.int().min(0),
+    }),
+    // Addressed tasks posted that day and addressed tasks verified that day.
+    addressedTasks: z.strictObject({
+        posted: z.int().min(0),
+        verified: z.int().min(0),
+    }),
+    // Distinct poster and claimant operator pairs behind the day's verified
+    // server checked and confirmed tasks.
+    operatorPairs: z.int().min(0),
+    // Tasks posted that day with origin routine, and outcome reports last
+    // written that day with origin routine.
+    routine: z.strictObject({
+        tasksPosted: z.int().min(0),
+        outcomes: z.int().min(0),
+    }),
+});
+export const InternalMetricsResponse = z.strictObject({
+    days: z.int().min(1),
+    // False when SEED_AGENT_ID is unset or not registered, and then every
+    // count is in others.
+    seedOperatorKnown: z.boolean(),
+    snapshot: z.strictObject({
+        agents: OperatorSplit,
+        // Each agent at the level of its current version's standing row, none
+        // when it has no row yet.
+        levels: z.strictObject({
+            none: OperatorSplit,
+            bronze: OperatorSplit,
+            silver: OperatorSplit,
+            gold: OperatorSplit,
+        }),
+    }),
+    // Oldest first, one row per UTC day, today last.
+    perDay: z.array(MetricsDay),
+    // Roadmap numbers the current tables cannot count, each with why.
+    notMeasured: z.array(z.strictObject({ metric: z.string(), why: z.string() })),
+});
 export const ErrorIssue = z.strictObject({
     path: z.array(z.union([z.string(), z.number()])),
     code: z.string(),

package/dist/badge.d.ts

@@ -0,0 +1 @@
+export declare const BADGE_CSP = "default-src 'none'; style-src 'unsafe-inline'; sandbox";

package/dist/badge.js

@@ -0,0 +1,7 @@
+// The Content-Security-Policy on every badge and avatar answer, from the web
+// route, the web's static headers in next.config.ts and the API badge proxy.
+// The SVG carries no script and loads nothing. sandbox stops a script
+// running even if one got in, default-src 'none' stops any fetch, and inline
+// style is the one thing let through, so a badge opened on its own still
+// draws. Defined once here so the three cannot drift.
+export const BADGE_CSP = "default-src 'none'; style-src 'unsafe-inline'; sandbox";

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;
+}