@sealkeeper/schema 0.0.1 → 0.4.1

package/dist/seal-conformance.js

@@ -0,0 +1,176 @@
+import { signAsync } from '@noble/ed25519';
+import { generateKeypair } from './agent-id.js';
+import { base64urlEncode, utf8Encode } from './base64url.js';
+import { CREDENTIAL_ISSUER, LEGACY_ISSUER_UNTIL, LEGACY_ISSUERS, SEAL_CLOCK_SKEW_SECONDS, SEAL_MAX_TTL_SECONDS, SEAL_VERSION, } from './credential.js';
+import { sign } from './envelope.js';
+const KID = 'vouched-conformance-1';
+// 1 October 2026, after LEGACY_UNTIL, so no case leans on the legacy shape,
+// and before LEGACY_ISSUER_UNTIL, so a legacy issuer is still accepted.
+const NOW = 1_790_812_800;
+const LEGACY_ISSUER = LEGACY_ISSUERS[0];
+const HOUR = 3600;
+const header = (kid) => base64urlEncode(utf8Encode(JSON.stringify({ alg: 'EdDSA', kid })));
+// Signs payload bytes as they are, so a case can carry a payload that is not
+// JSON. sign() in envelope.ts always writes JSON.
+async function signRaw(body, privateKey, kid) {
+    const input = `${header(kid)}.${base64urlEncode(utf8Encode(body))}`;
+    const signature = await signAsync(utf8Encode(input), privateKey);
+    return `${input}.${base64urlEncode(signature)}`;
+}
+export async function sealConformanceCases() {
+    const pair = await generateKeypair();
+    const other = await generateKeypair();
+    const base = {
+        iss: CREDENTIAL_ISSUER,
+        sub: pair.agentId,
+        ver: SEAL_VERSION,
+        iat: NOW - HOUR,
+        exp: NOW + 23 * HOUR,
+        agent_version: '1.0.0',
+        version: '1.0.0',
+        level: 'bronze',
+        scores: { reliability: 0.9, safety: null },
+        counts: {
+            events: 40,
+            history_days: 4,
+            verified_tasks: 26,
+            seed_tasks: 25,
+            server_checked_tasks: 1,
+            confirmed_tasks: 0,
+            distinct_operators: 1,
+            safety_incidents_90d: 0,
+        },
+        operator: { verified: false },
+        identity: [],
+        last_active: NOW - HOUR,
+        dormant_days: 0,
+    };
+    const signed = (payload) => sign(payload, pair.privateKey, KID);
+    const valid = await signed(base);
+    const [h, , s] = valid.split('.');
+    const altered = `${h}.${base64urlEncode(utf8Encode(JSON.stringify({ ...base, level: 'gold' })))}.${s}`;
+    const cases = [
+        ['a valid SEAL', valid, 'valid'],
+        [
+            'iat ahead of now within the clock skew',
+            signed({
+                ...base,
+                iat: NOW + SEAL_CLOCK_SKEW_SECONDS,
+                exp: NOW + SEAL_CLOCK_SKEW_SECONDS + 23 * HOUR,
+            }),
+            'valid',
+        ],
+        [
+            'expired',
+            signed({ ...base, iat: NOW - 25 * HOUR, exp: NOW - HOUR }),
+            'expired',
+        ],
+        [
+            'expiring this second',
+            signed({ ...base, iat: NOW - 24 * HOUR, exp: NOW }),
+            'expired',
+        ],
+        [
+            'iat in the future past the clock skew',
+            signed({
+                ...base,
+                iat: NOW + SEAL_CLOCK_SKEW_SECONDS + 1,
+                exp: NOW + SEAL_CLOCK_SKEW_SECONDS + 1 + 23 * HOUR,
+            }),
+            'not_yet_valid',
+        ],
+        ['an unknown ver', signed({ ...base, ver: 2 }), 'unsupported_version'],
+        [
+            'no ver after the legacy cutoff',
+            signed({ ...base, ver: undefined }),
+            'unsupported_version',
+        ],
+        [
+            'the wrong shape, a level not in the standard',
+            signed({ ...base, level: 'platinum' }),
+            'malformed',
+        ],
+        [
+            'a score above 1',
+            signed({ ...base, scores: { reliability: 1.2 } }),
+            'malformed',
+        ],
+        [
+            'a negative count',
+            signed({
+                ...base,
+                counts: { ...base.counts, events: -1 },
+            }),
+            'malformed',
+        ],
+        [
+            'exp more than 24 hours after iat',
+            signed({ ...base, exp: base.iat + SEAL_MAX_TTL_SECONDS + 1 }),
+            'malformed',
+        ],
+        [
+            'a signed payload that is not JSON',
+            signRaw('not json', pair.privateKey, KID),
+            'malformed',
+        ],
+        [
+            'the wrong issuer, full payload',
+            signed({ ...base, iss: 'other.example' }),
+            'wrong_issuer',
+        ],
+        [
+            'the wrong issuer, a payload in no SEAL shape',
+            signed({ iss: 'other.example', sub: 'someone' }),
+            'wrong_issuer',
+        ],
+        [
+            'a legacy issuer before LEGACY_ISSUER_UNTIL',
+            signed({ ...base, iss: LEGACY_ISSUER }),
+            'valid',
+        ],
+        [
+            'a legacy issuer from LEGACY_ISSUER_UNTIL on',
+            signed({
+                ...base,
+                iss: LEGACY_ISSUER,
+                iat: LEGACY_ISSUER_UNTIL - HOUR,
+                exp: LEGACY_ISSUER_UNTIL + 23 * HOUR,
+                last_active: LEGACY_ISSUER_UNTIL - HOUR,
+            }),
+            'wrong_issuer',
+            LEGACY_ISSUER_UNTIL,
+        ],
+        ['not a JWS', 'not.a.seal', 'malformed'],
+        [
+            'a kid no published key has',
+            sign(base, other.privateKey, 'retired-1'),
+            'unknown_kid',
+        ],
+        ['a payload altered after signing', altered, 'bad_signature'],
+        [
+            'signed by another key under the published kid',
+            sign(base, other.privateKey, KID),
+            'bad_signature',
+        ],
+    ];
+    return {
+        nowSeconds: NOW,
+        wellKnown: {
+            keys: [
+                {
+                    kid: KID,
+                    kty: 'OKP',
+                    crv: 'Ed25519',
+                    alg: 'EdDSA',
+                    x: base64urlEncode(pair.publicKey),
+                },
+            ],
+        },
+        cases: await Promise.all(cases.map(async ([name, jws, expected, nowSeconds]) => ({
+            name,
+            jws: await jws,
+            expected,
+            ...(nowSeconds === undefined ? {} : { nowSeconds }),
+        }))),
+    };
+}

package/dist/standing.d.ts

@@ -0,0 +1,46 @@
+import { z } from 'zod';
+export declare const Level: z.ZodEnum<{
+    bronze: "bronze";
+    gold: "gold";
+    none: "none";
+    silver: "silver";
+}>;
+export type Level = z.infer<typeof Level>;
+export declare const LEVEL_RANK: Record<Level, number>;
+export declare const StandingCounts: z.ZodObject<{
+    events: z.ZodInt;
+    history_days: z.ZodInt;
+    verified_tasks: z.ZodInt;
+    seed_tasks: z.ZodInt;
+    server_checked_tasks: z.ZodInt;
+    confirmed_tasks: z.ZodInt;
+    distinct_operators: z.ZodInt;
+    safety_incidents_90d: z.ZodInt;
+}, z.core.$strict>;
+export type StandingCounts = z.infer<typeof StandingCounts>;
+export declare const DAY_MS = 86400000;
+export declare const DORMANCY: {
+    readonly quietDays: 14;
+    readonly dropOneDays: 30;
+    readonly dropTwoDays: 60;
+    readonly noneDays: 90;
+};
+export declare function dormantDays(lastActive: Date | null, now: Date): number | null;
+export declare const isQuiet: (days: number | null) => boolean;
+export declare const Standing: z.ZodObject<{
+    counts: z.ZodObject<{
+        events: z.ZodInt;
+        history_days: z.ZodInt;
+        verified_tasks: z.ZodInt;
+        seed_tasks: z.ZodInt;
+        server_checked_tasks: z.ZodInt;
+        confirmed_tasks: z.ZodInt;
+        distinct_operators: z.ZodInt;
+        safety_incidents_90d: z.ZodInt;
+    }, z.core.$strict>;
+    history_days: z.ZodInt;
+    last_active: z.ZodNullable<z.ZodISODateTime>;
+    dormant_days: z.ZodNullable<z.ZodInt>;
+    quiet: z.ZodBoolean;
+}, z.core.$strict>;
+export type Standing = z.infer<typeof Standing>;

package/dist/standing.js

@@ -0,0 +1,79 @@
+import { z } from 'zod';
+// Standing levels from the SEAL standard, section 5, lowest first. none is
+// below bronze. Every scored agent version has one.
+export const Level = z.enum(['none', 'bronze', 'silver', 'gold']);
+// Higher is better. The leaderboard sorts on it before the score.
+export const LEVEL_RANK = {
+    none: 0,
+    bronze: 1,
+    silver: 2,
+    gold: 3,
+};
+const Count = z.int().min(0);
+// The evidence counts of the SEAL standard, section 4, over the scoring
+// window (180 days) for one agent version. The names are the standard's, so
+// they carry over to the SEAL unchanged.
+//
+//   events                signed events accepted in the window
+//   history_days          distinct UTC days with an accepted event, the
+//                         agent's across all its versions
+//   verified_tasks        seed_tasks + server_checked_tasks + confirmed_tasks
+//   seed_tasks            verified tasks the seed agent posted
+//   server_checked_tasks  hash or schema tasks from another operator's agent
+//   confirmed_tasks       counterparty tasks from another operator's agent,
+//                         both sides reported and the reports agree
+//   distinct_operators    operators other than the agent's own behind its
+//                         server checked and confirmed tasks
+//   safety_incidents_90d  incident events in the last 90 days
+//
+// verified_tasks is always the sum of the three kinds, for a new version's
+// inherited counts too, and a SEAL whose counts break that does not parse.
+export const StandingCounts = z
+    .strictObject({
+    events: Count,
+    history_days: Count,
+    verified_tasks: Count,
+    seed_tasks: Count,
+    server_checked_tasks: Count,
+    confirmed_tasks: Count,
+    distinct_operators: Count,
+    safety_incidents_90d: Count,
+})
+    .refine((c) => c.verified_tasks ===
+    c.seed_tasks + c.server_checked_tasks + c.confirmed_tasks, {
+    message: 'verified_tasks must equal seed_tasks + server_checked_tasks + confirmed_tasks',
+    path: ['verified_tasks'],
+});
+export const DAY_MS = 86_400_000;
+// The dormancy ladder of the SEAL standard, section 5, in whole days since
+// the agent's last accepted event. At quietDays the badge shows quiet and
+// the level stays. At dropOneDays and dropTwoDays the level drops one step
+// each. At noneDays the level is none and no SEAL is issued. The scoring
+// job applies it and the CLI explains it, so it lives here.
+export const DORMANCY = {
+    quietDays: 14,
+    dropOneDays: 30,
+    dropTwoDays: 60,
+    noneDays: 90,
+};
+// Whole days from lastActive to now, never below zero. null when the agent
+// has sent no accepted event. The one place dormancy is counted.
+export function dormantDays(lastActive, now) {
+    if (lastActive === null)
+        return null;
+    return Math.max(0, Math.floor((now.getTime() - lastActive.getTime()) / DAY_MS));
+}
+// True at quietDays or more. Never active is not quiet.
+export const isQuiet = (days) => days !== null && days >= DORMANCY.quietDays;
+// What the agent answers carry beside level, read from the standing table
+// for the current version. last_active is the newest accepted event of the
+// agent on any version, null when it has sent none. dormant_days is whole
+// days since last_active at the time of the answer, null with it. quiet is
+// true when dormant_days is at DORMANCY.quietDays or more.
+export const Standing = z.strictObject({
+    counts: StandingCounts,
+    history_days: Count,
+    last_active: z.iso.datetime().nullable(),
+    dormant_days: Count.nullable(),
+    quiet: z.boolean(),
+});

package/dist/tasks.d.ts

@@ -0,0 +1,49 @@
+import { z } from 'zod';
+export declare const Sha256Hex: z.ZodString;
+export declare const JSON_SCHEMA_MAX_BYTES = 16384;
+export declare const HashVerification: z.ZodObject<{
+    kind: z.ZodLiteral<"hash">;
+    sha256: z.ZodString;
+}, z.core.$strict>;
+export declare const SchemaVerification: z.ZodObject<{
+    kind: z.ZodLiteral<"schema">;
+    jsonSchema: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+}, z.core.$strict>;
+export declare const CounterpartyVerification: z.ZodObject<{
+    kind: z.ZodLiteral<"counterparty">;
+}, z.core.$strict>;
+export declare const VerificationSpec: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    kind: z.ZodLiteral<"hash">;
+    sha256: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"schema">;
+    jsonSchema: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"counterparty">;
+}, z.core.$strict>], "kind">;
+export type VerificationSpec = z.infer<typeof VerificationSpec>;
+export declare const TaskOutcome: z.ZodEnum<{
+    failure: "failure";
+    success: "success";
+}>;
+export type TaskOutcome = z.infer<typeof TaskOutcome>;
+export declare const TaskState: z.ZodEnum<{
+    claimed: "claimed";
+    expired: "expired";
+    open: "open";
+    submitted: "submitted";
+    verified: "verified";
+}>;
+export type TaskState = z.infer<typeof TaskState>;
+type Timestamp = Date | string;
+export type TaskTimestamps = {
+    claimedAt: Timestamp | null;
+    submittedAt: Timestamp | null;
+    verifiedAt: Timestamp | null;
+    expiresAt: Timestamp;
+};
+export declare function taskState(task: TaskTimestamps, now?: Date): TaskState;
+type JsonObject = Record<string, unknown>;
+export declare function redactJsonSchema(schema: JsonObject): JsonObject;
+export declare function publicVerification(spec: VerificationSpec): VerificationSpec;
+export {};

package/dist/tasks.js

@@ -0,0 +1,132 @@
+import { z } from 'zod';
+import { utf8Encode } from './base64url.js';
+export const Sha256Hex = z.string().regex(/^[0-9a-f]{64}$/);
+export const JSON_SCHEMA_MAX_BYTES = 16384;
+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`),
+});
+export const CounterpartyVerification = z.strictObject({
+    kind: z.literal('counterparty'),
+});
+export const VerificationSpec = z.discriminatedUnion('kind', [
+    HashVerification,
+    SchemaVerification,
+    CounterpartyVerification,
+]);
+export const TaskOutcome = z.enum(['success', 'failure']);
+export const TaskState = z.enum([
+    'open',
+    'claimed',
+    'submitted',
+    'verified',
+    'expired',
+]);
+export function taskState(task, now = new Date()) {
+    if (task.verifiedAt !== null)
+        return 'verified';
+    if (new Date(task.expiresAt).getTime() <= now.getTime())
+        return 'expired';
+    if (task.submittedAt !== null)
+        return 'submitted';
+    if (task.claimedAt !== null)
+        return 'claimed';
+    return 'open';
+}
+/*
+ * The public view of a task's JSON schema. A schema task can pin its expected
+ * values with const, enum or pattern, so the stored schema may contain the
+ * answer. Reads show this redacted copy and submit verifies against the full
+ * one, which never leaves the server.
+ *
+ * An allowlist, not a denylist. Only keywords that describe the shape are
+ * kept, so a keyword added later cannot leak by default. Subschemas under
+ * properties, items, prefixItems and additionalProperties are redacted the
+ * same way. Everything else (const, enum, pattern, examples, default, anyOf,
+ * $ref, $defs, description and the rest) is dropped.
+ */
+const SHAPE_DATA = new Set([
+    'type',
+    'required',
+    'minimum',
+    'maximum',
+    'exclusiveMinimum',
+    'exclusiveMaximum',
+    'minLength',
+    'maxLength',
+    'minItems',
+    'maxItems',
+]);
+const SHAPE_ONE = new Set(['items', 'additionalProperties']);
+const isJsonObject = (v) => typeof v === 'object' && v !== null && !Array.isArray(v);
+// A boolean is a valid subschema and says nothing about the answer, so it
+// stays. Anything else that is not an object becomes the empty schema.
+function redactSubschema(node) {
+    if (typeof node === 'boolean')
+        return node;
+    return isJsonObject(node) ? redactJsonSchema(node) : {};
+}
+const BOUNDS = [
+    'minimum',
+    'maximum',
+    'exclusiveMinimum',
+    'exclusiveMaximum',
+];
+const finite = (v) => typeof v === 'number' && Number.isFinite(v) ? v : undefined;
+// True when the numeric bounds leave room for one value only, such as
+// minimum 42 with maximum 42, or an integer above 41 and below 43. Those
+// pin the answer as surely as const, so the redacted copy drops all four
+// bounds (VOU-107). Not exported, so the schema package's exports stay
+// the ones on npm.
+function boundsPinOneValue(schema) {
+    const [min, max, xmin, xmax] = BOUNDS.map((k) => finite(schema[k]));
+    if (min !== undefined && min === max)
+        return true;
+    // Null never meets a numeric bound, so a nullable integer leaks the
+    // same one value as a plain integer.
+    const types = Array.isArray(schema.type) ? schema.type : [schema.type];
+    const numeric = types.filter((t) => t !== 'null');
+    if (numeric.length === 0 || !numeric.every((t) => t === 'integer')) {
+        return false;
+    }
+    const lo = Math.max(min === undefined ? -Infinity : Math.ceil(min), xmin === undefined ? -Infinity : Math.floor(xmin) + 1);
+    const hi = Math.min(max === undefined ? Infinity : Math.floor(max), xmax === undefined ? Infinity : Math.ceil(xmax) - 1);
+    return lo === hi;
+}
+export function redactJsonSchema(schema) {
+    const pinned = boundsPinOneValue(schema);
+    const out = {};
+    for (const [key, value] of Object.entries(schema)) {
+        if (pinned && BOUNDS.includes(key))
+            continue;
+        if (SHAPE_DATA.has(key)) {
+            out[key] = Array.isArray(value) ? [...value] : value;
+        }
+        else if (SHAPE_ONE.has(key)) {
+            out[key] = redactSubschema(value);
+        }
+        else if (key === 'prefixItems' && Array.isArray(value)) {
+            out[key] = value.map(redactSubschema);
+        }
+        else if (key === 'properties' && isJsonObject(value)) {
+            out[key] = Object.fromEntries(Object.entries(value).map(([name, sub]) => [
+                name,
+                redactSubschema(sub),
+            ]));
+        }
+    }
+    return out;
+}
+// What GET /v1/tasks and GET /v1/tasks/:id show. Hash and counterparty specs
+// are already safe to show, a sha256 is one way.
+export function publicVerification(spec) {
+    if (spec.kind !== 'schema')
+        return spec;
+    return { kind: 'schema', jsonSchema: redactJsonSchema(spec.jsonSchema) };
+}

package/dist/top-dimensions.d.ts

@@ -0,0 +1,9 @@
+import { BaseDimension } from './dimensions.js';
+export type TopDimension = {
+    dimension: BaseDimension;
+    value: number;
+};
+export declare function topBaseDimensions(scores: readonly {
+    dimension: string;
+    value: number | null;
+}[], count: number): TopDimension[];

package/dist/top-dimensions.js

@@ -0,0 +1,13 @@
+import { BaseDimension } from './dimensions.js';
+// Base dimensions with a value, highest first. Ties keep the fixed order of
+// BaseDimension. Callers that want trust only filter with isTrustDimension
+// first.
+export function topBaseDimensions(scores, count) {
+    const ranked = [];
+    for (const d of BaseDimension.options) {
+        const value = scores.find((s) => s.dimension === d)?.value;
+        if (typeof value === 'number')
+            ranked.push({ dimension: d, value });
+    }
+    return ranked.sort((a, b) => b.value - a.value).slice(0, count);
+}

package/package.json

@@ -1,9 +1,73 @@
 {
   "name": "@sealkeeper/schema",
-  "version": "0.0.1",
-  "description": "Sealkeeper shared schema. Placeholder until the first release.",
+  "version": "0.4.1",
+  "private": false,
+  "description": "Zod schemas, event taxonomy and signing helpers for SealKeeper.",
   "license": "Apache-2.0",
-  "homepage": "https://sealkeeper.run",
-  "publishConfig": { "access": "public" },
-  "files": ["README.md"]
+  "homepage": "https://sealkeeper.run/seal/standard",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/sealkeeper-dev/sealkeeper.git",
+    "directory": "packages/schema"
+  },
+  "bugs": {
+    "url": "https://github.com/sealkeeper-dev/cli/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./conformance": {
+      "types": "./dist/seal-conformance.d.ts",
+      "default": "./dist/seal-conformance.js"
+    },
+    "./db": {
+      "types": "./dist/db/index.d.ts",
+      "default": "./dist/db/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE",
+    "NOTICE"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "prepublishOnly": "rm -rf dist && pnpm run build",
+    "test": "tsc -p tsconfig.json && vitest run",
+    "db:generate": "drizzle-kit generate",
+    "db:migrate": "drizzle-kit migrate",
+    "db:migrate:prod": "node dist/db/migrate.js"
+  },
+  "dependencies": {
+    "@noble/ed25519": "^3.2.0",
+    "zod": "^4.6.5"
+  },
+  "peerDependencies": {
+    "drizzle-orm": "^0.45.3",
+    "postgres": "^3.4.9"
+  },
+  "peerDependenciesMeta": {
+    "drizzle-orm": {
+      "optional": true
+    },
+    "postgres": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/node": "^24.13.6",
+    "drizzle-kit": "^0.31.11",
+    "drizzle-orm": "^0.45.3",
+    "postgres": "^3.4.9",
+    "typescript": "^7.0.2",
+    "vitest": "^5.0.1"
+  }
 }