@abloh/core 0.1.2 → 1.0.0

package/dist/playground-admission.d.ts

@@ -0,0 +1,142 @@
+/**
+ * THE EXECUTABLE SCHEMA KERNEL: one declaration per wire boundary, everything else derived.
+ *
+ * WHY THIS EXISTS. The fact-divergence audit found the same shape declared twice on twenty-one
+ * boundaries: a producer writes the object, a consumer re-types it, and neither reads the other.
+ * They agree in one checkout and drift the moment one side changes - and because a customer runs a
+ * PINNED Action, a PINNED CLI or a PINNED GitHub App against a service that moved, the drift is not
+ * a same-build risk that a test comparing the two copies could catch. Two of these already cost
+ * real runs: a runner emitting a valid new state made the service discard every Angular and Deno
+ * upload, and an added field made a pinned GitHub App throw away a whole check.
+ *
+ * WHAT A CONTRACT DECLARES ONCE, and what is derived from it rather than written beside it:
+ *
+ *   the TypeScript type          `Infer<typeof C>` - the type IS the schema, not a copy of it
+ *   the consumer parser          `C.parse(value)` - one refusal grammar, one path syntax
+ *   the producer projection      `project(C, value)` - drops what the contract does not carry
+ *   every discriminator value    `C.fields.x.values` - the enum tuple, readable at runtime
+ *   every limit                  `C.fields.x.max` - the cap, readable by producer and consumer
+ *
+ * THE UNKNOWN-FIELD POSTURE IS DECLARED, NOT ASSUMED, and it is the single most important field on
+ * an object node. Two different boundaries want opposite answers and both are right:
+ *
+ *   `unknownFields: "refuse"` is an INGEST DOOR. The service stores what it accepts and serves it
+ *   to a customer surface, so a key it does not know is a producer attaching something the boundary
+ *   never agreed to carry - a source slice on a row that is supposed to be a path. Refusing is the
+ *   privacy posture and it must stay.
+ *
+ *   `unknownFields: "ignore"` is a PINNED CONSUMER reading a NEWER PRODUCER. The GitHub App parsing
+ *   the service's evidence object cannot refuse a field that did not exist when it was released;
+ *   that exact refusal discarded a whole check. Additive change is the normal direction of travel
+ *   on these boundaries, and a consumer that cannot survive it is a released-version outage.
+ *
+ * FAILURE IS A PATH AND A CAUSE, never a boolean. `runResult.fixLoop.summaries[3].verdict` tells a
+ * maintainer which field of which row, which is what the hand-written validators were already
+ * doing one string concatenation at a time.
+ *
+ * NOT A VALIDATION LIBRARY. It has exactly the node kinds these boundaries use. A boundary that
+ * needs something else adds the node here, once, rather than hand-writing its own validator again.
+ */
+/** Where in the document a value sat, in the syntax a maintainer reads in a refusal. */
+type WirePath = string;
+type WireResult<T> = {
+    ok: true;
+    value: T;
+} | {
+    ok: false;
+    error: string;
+};
+/**
+ * A node in a wire contract.
+ *
+ * `kind` and the per-kind reflection fields are what make a contract READABLE rather than only
+ * runnable: the limits mechanism (F27, F55, F60) needs the cap as a number, and the vocabulary
+ * mechanism (F11, F23, F54, F85) needs the enum as a tuple. A validator that only validated would
+ * leave those facts owned somewhere else again.
+ */
+interface WireNode<T> {
+    readonly kind: string;
+    /** Parse an unknown value from the wire. `path` is where it sat, for the refusal sentence. */
+    parse(value: unknown, path?: WirePath): WireResult<T>;
+}
+type Infer<N> = N extends WireNode<infer T> ? T : never;
+/**
+ * A field of an object contract: its node, and whether the wire may leave it out.
+ *
+ * `Optional` IS A LITERAL TYPE PARAMETER rather than a `boolean` property, because the inferred
+ * TypeScript type is derived from it. Widened to `boolean`, every field reads as required and the
+ * generated type stops matching the parser beside it - which would put the two back out of step in
+ * the one place this kernel exists to keep them together.
+ */
+interface WireField<T, Optional extends boolean = boolean> {
+    readonly node: WireNode<T>;
+    readonly optional: Optional;
+}
+type WireFields = Record<string, WireField<unknown, boolean>>;
+type RequiredKeys<F extends WireFields> = {
+    [K in keyof F]: F[K]["optional"] extends true ? never : K;
+}[keyof F];
+type OptionalKeys<F extends WireFields> = {
+    [K in keyof F]: F[K]["optional"] extends true ? K : never;
+}[keyof F];
+type InferFields<F extends WireFields> = {
+    [K in RequiredKeys<F>]: Infer<F[K]["node"]>;
+} & {
+    [K in OptionalKeys<F>]?: Infer<F[K]["node"]>;
+};
+/** What a consumer does with a key the contract does not declare. See the file header. */
+type UnknownFieldPosture = "refuse" | "ignore";
+interface WireObject<F extends WireFields> extends WireNode<InferFields<F>> {
+    readonly kind: "object";
+    readonly fields: F;
+    readonly unknownFields: UnknownFieldPosture;
+    /** The declared key names, in declaration order - the field allowlist, derived not re-typed. */
+    readonly keys: readonly (keyof F & string)[];
+}
+
+declare const PLAYGROUND_HOUR_MS = 3600000;
+declare const PLAYGROUND_DAY_MS: number;
+declare const PLAYGROUND_BROWSER_ACTIVE = 1;
+declare const PLAYGROUND_BROWSER_HOURLY = 3;
+declare const PLAYGROUND_BROWSER_DAILY = 10;
+declare const PLAYGROUND_IP_HOURLY = 30;
+declare const PLAYGROUND_IP_DAILY = 100;
+declare const PLAYGROUND_ADMISSION_ENDINGS: {
+    readonly PLAYGROUND_ACTIVE_RUN_LIMIT: "playground-browser-active-limit";
+    readonly PLAYGROUND_HOURLY_LIMIT: "playground-hourly-limit";
+    readonly PLAYGROUND_DAILY_LIMIT: "playground-browser-daily-limit";
+    readonly PLAYGROUND_IP_HOURLY_LIMIT: "playground-ip-hourly-limit";
+    readonly PLAYGROUND_IP_DAILY_LIMIT: "playground-ip-daily-limit";
+    readonly PLAYGROUND_BUSY: "playground-capacity";
+    readonly PLAYGROUND_GLOBAL_HOURLY_LIMIT: "playground-global-hourly-limit";
+    readonly PLAYGROUND_VERIFICATION_REQUIRED: "playground-verification-required";
+    readonly PLAYGROUND_VERIFICATION_UNAVAILABLE: "playground-verification-unavailable";
+    readonly PLAYGROUND_INGRESS_UNAVAILABLE: "playground-ingress-unavailable";
+    readonly PLAYGROUND_ADMISSION_UNAVAILABLE: "playground-admission-unavailable";
+};
+type PlaygroundAdmissionCode = keyof typeof PLAYGROUND_ADMISSION_ENDINGS;
+declare const PLAYGROUND_MODEL_LIMITS: Readonly<{
+    requests: 8;
+    runUsd: 1;
+    hourUsd: 1.5;
+    dayUsd: 12.5;
+}>;
+declare const playgroundAdmissionErrorContract: WireObject<{
+    readonly code: WireField<"PLAYGROUND_ACTIVE_RUN_LIMIT" | "PLAYGROUND_HOURLY_LIMIT" | "PLAYGROUND_DAILY_LIMIT" | "PLAYGROUND_IP_HOURLY_LIMIT" | "PLAYGROUND_IP_DAILY_LIMIT" | "PLAYGROUND_BUSY" | "PLAYGROUND_GLOBAL_HOURLY_LIMIT" | "PLAYGROUND_VERIFICATION_REQUIRED" | "PLAYGROUND_VERIFICATION_UNAVAILABLE" | "PLAYGROUND_INGRESS_UNAVAILABLE" | "PLAYGROUND_ADMISSION_UNAVAILABLE", false>;
+    readonly message: WireField<string, false>;
+    readonly ending: WireField<"playground-browser-active-limit" | "playground-hourly-limit" | "playground-browser-daily-limit" | "playground-ip-hourly-limit" | "playground-ip-daily-limit" | "playground-capacity" | "playground-global-hourly-limit" | "playground-verification-required" | "playground-verification-unavailable" | "playground-ingress-unavailable" | "playground-admission-unavailable", false>;
+    readonly retryAt: WireField<string | null, false>;
+}>;
+type PlaygroundAdmissionFailure = Infer<typeof playgroundAdmissionErrorContract>;
+declare function parsePlaygroundAdmissionFailure(value: unknown): PlaygroundAdmissionFailure | null;
+/** Bump when the worker/public contract required to execute a visitor job changes. */
+declare const PLAYGROUND_WORKER_CONTRACT = "playground-visitor-jobs/v1";
+declare const PLAYGROUND_WORKER_HEARTBEAT_MS = 5000;
+declare const PLAYGROUND_WORKER_LEASE_MS = 20000;
+declare const playgroundReadinessContract: WireObject<{
+    readonly contract: WireField<string, false>;
+    readonly ready: WireField<boolean, false>;
+}>;
+declare function parsePlaygroundReadiness(value: unknown): boolean;
+
+export { PLAYGROUND_ADMISSION_ENDINGS, PLAYGROUND_BROWSER_ACTIVE, PLAYGROUND_BROWSER_DAILY, PLAYGROUND_BROWSER_HOURLY, PLAYGROUND_DAY_MS, PLAYGROUND_HOUR_MS, PLAYGROUND_IP_DAILY, PLAYGROUND_IP_HOURLY, PLAYGROUND_MODEL_LIMITS, PLAYGROUND_WORKER_CONTRACT, PLAYGROUND_WORKER_HEARTBEAT_MS, PLAYGROUND_WORKER_LEASE_MS, type PlaygroundAdmissionCode, type PlaygroundAdmissionFailure, parsePlaygroundAdmissionFailure, parsePlaygroundReadiness, playgroundAdmissionErrorContract, playgroundReadinessContract };

package/dist/playground-admission.js

@@ -0,0 +1,166 @@
+// src/wire/schema-kernel.ts
+function fail(path, what) {
+  return { ok: false, error: path === "" ? what : `${path} ${what}` };
+}
+function child(path, key) {
+  return path === "" ? key : `${path}.${key}`;
+}
+function wireEnum(values) {
+  const set = new Set(values);
+  const has = (value) => set.has(value);
+  return {
+    kind: "enum",
+    values,
+    has,
+    parse(value, path = "") {
+      if (typeof value !== "string") return fail(path, `must be one of ${values.join(", ")}`);
+      if (!set.has(value)) return fail(path, `is ${JSON.stringify(value)}, which is not one of ${values.join(", ")}`);
+      return { ok: true, value };
+    }
+  };
+}
+function wireString(options = {}) {
+  const min = options.min ?? 0;
+  const bound = options.maxBytes !== void 0 ? { unit: "bytes", max: options.maxBytes } : options.max !== void 0 ? { unit: "characters", max: options.max } : void 0;
+  return {
+    kind: "string",
+    ...options.max === void 0 ? {} : { max: options.max },
+    ...options.maxBytes === void 0 ? {} : { maxBytes: options.maxBytes },
+    ...bound === void 0 ? {} : { bound },
+    ...options.pattern === void 0 ? {} : { pattern: options.pattern },
+    min,
+    parse(value, path = "") {
+      if (typeof value !== "string") return fail(path, "must be a string");
+      if (value.length < min) return fail(path, min === 1 ? "must not be empty" : `must be at least ${min} characters`);
+      if (options.max !== void 0 && value.length > options.max) {
+        return fail(path, `must be at most ${options.max} characters, and is ${value.length}`);
+      }
+      if (options.maxBytes !== void 0 && new TextEncoder().encode(value).length > options.maxBytes) {
+        return fail(path, `must be at most ${options.maxBytes} bytes, and is ${new TextEncoder().encode(value).length}`);
+      }
+      if (options.pattern !== void 0 && !options.pattern.test(value)) {
+        return fail(path, `must be ${options.patternIs ?? `written as ${String(options.pattern)}`}`);
+      }
+      return { ok: true, value };
+    }
+  };
+}
+function wireBoolean() {
+  return {
+    kind: "boolean",
+    parse(value, path = "") {
+      if (typeof value !== "boolean") return fail(path, "must be a boolean");
+      return { ok: true, value };
+    }
+  };
+}
+function wireNullable(inner) {
+  return {
+    kind: "nullable",
+    inner,
+    parse(value, path = "") {
+      if (value === null) return { ok: true, value: null };
+      return inner.parse(value, path);
+    }
+  };
+}
+function required(node) {
+  return { node, optional: false };
+}
+function wireObject(fields, options) {
+  const keys = Object.keys(fields);
+  return {
+    kind: "object",
+    fields,
+    unknownFields: options.unknownFields,
+    keys,
+    parse(value, path = "") {
+      if (typeof value !== "object" || value === null || Array.isArray(value)) return fail(path, "must be an object");
+      const record = value;
+      if (options.unknownFields === "refuse") {
+        for (const key of Object.keys(record)) {
+          if (!Object.prototype.hasOwnProperty.call(fields, key)) return fail(child(path, key), "is not a field of this contract");
+        }
+      }
+      const out = {};
+      for (const key of keys) {
+        const field = fields[key];
+        const raw = record[key];
+        if (raw === void 0) {
+          if (!field.optional) return fail(child(path, key), "is required");
+          continue;
+        }
+        const parsed = field.node.parse(raw, child(path, key));
+        if (!parsed.ok) return parsed;
+        if (parsed.value !== void 0) out[key] = parsed.value;
+      }
+      return { ok: true, value: out };
+    }
+  };
+}
+
+// src/wire/playground-admission.ts
+var PLAYGROUND_HOUR_MS = 36e5;
+var PLAYGROUND_DAY_MS = 24 * PLAYGROUND_HOUR_MS;
+var PLAYGROUND_BROWSER_ACTIVE = 1;
+var PLAYGROUND_BROWSER_HOURLY = 3;
+var PLAYGROUND_BROWSER_DAILY = 10;
+var PLAYGROUND_IP_HOURLY = 30;
+var PLAYGROUND_IP_DAILY = 100;
+var PLAYGROUND_ADMISSION_ENDINGS = {
+  PLAYGROUND_ACTIVE_RUN_LIMIT: "playground-browser-active-limit",
+  PLAYGROUND_HOURLY_LIMIT: "playground-hourly-limit",
+  PLAYGROUND_DAILY_LIMIT: "playground-browser-daily-limit",
+  PLAYGROUND_IP_HOURLY_LIMIT: "playground-ip-hourly-limit",
+  PLAYGROUND_IP_DAILY_LIMIT: "playground-ip-daily-limit",
+  PLAYGROUND_BUSY: "playground-capacity",
+  PLAYGROUND_GLOBAL_HOURLY_LIMIT: "playground-global-hourly-limit",
+  PLAYGROUND_VERIFICATION_REQUIRED: "playground-verification-required",
+  PLAYGROUND_VERIFICATION_UNAVAILABLE: "playground-verification-unavailable",
+  PLAYGROUND_INGRESS_UNAVAILABLE: "playground-ingress-unavailable",
+  PLAYGROUND_ADMISSION_UNAVAILABLE: "playground-admission-unavailable"
+};
+var PLAYGROUND_MODEL_LIMITS = Object.freeze({ requests: 8, runUsd: 1, hourUsd: 1.5, dayUsd: 12.5 });
+var playgroundAdmissionErrorContract = wireObject({
+  code: required(wireEnum(Object.keys(PLAYGROUND_ADMISSION_ENDINGS))),
+  message: required(wireString({ min: 1, max: 1024 })),
+  ending: required(wireEnum(Object.values(PLAYGROUND_ADMISSION_ENDINGS))),
+  retryAt: required(wireNullable(wireString({ min: 24, max: 24 })))
+}, { unknownFields: "refuse" });
+function parsePlaygroundAdmissionFailure(value) {
+  const parsed = playgroundAdmissionErrorContract.parse(value);
+  if (!parsed.ok) return null;
+  const { code, ending, retryAt } = parsed.value;
+  if (PLAYGROUND_ADMISSION_ENDINGS[code] !== ending) return null;
+  if (retryAt !== null && (!Number.isFinite(Date.parse(retryAt)) || new Date(retryAt).toISOString() !== retryAt)) return null;
+  return parsed.value;
+}
+var PLAYGROUND_WORKER_CONTRACT = "playground-visitor-jobs/v1";
+var PLAYGROUND_WORKER_HEARTBEAT_MS = 5e3;
+var PLAYGROUND_WORKER_LEASE_MS = 2e4;
+var playgroundReadinessContract = wireObject({
+  contract: required(wireString({ min: 1, max: 100 })),
+  ready: required(wireBoolean())
+}, { unknownFields: "refuse" });
+function parsePlaygroundReadiness(value) {
+  const parsed = playgroundReadinessContract.parse(value);
+  return parsed.ok && parsed.value.contract === PLAYGROUND_WORKER_CONTRACT && parsed.value.ready;
+}
+export {
+  PLAYGROUND_ADMISSION_ENDINGS,
+  PLAYGROUND_BROWSER_ACTIVE,
+  PLAYGROUND_BROWSER_DAILY,
+  PLAYGROUND_BROWSER_HOURLY,
+  PLAYGROUND_DAY_MS,
+  PLAYGROUND_HOUR_MS,
+  PLAYGROUND_IP_DAILY,
+  PLAYGROUND_IP_HOURLY,
+  PLAYGROUND_MODEL_LIMITS,
+  PLAYGROUND_WORKER_CONTRACT,
+  PLAYGROUND_WORKER_HEARTBEAT_MS,
+  PLAYGROUND_WORKER_LEASE_MS,
+  parsePlaygroundAdmissionFailure,
+  parsePlaygroundReadiness,
+  playgroundAdmissionErrorContract,
+  playgroundReadinessContract
+};

package/dist/playground-ingress.d.ts

@@ -0,0 +1,18 @@
+declare const PLAYGROUND_INGRESS_HEADER = "x-playground-ingress";
+declare const PLAYGROUND_INGRESS_SECRET_KEY = "ABLOH_PLAYGROUND_INGRESS_SECRET";
+declare const PLAYGROUND_CHALLENGE_HEADER = "x-playground-challenge";
+declare const PLAYGROUND_CHALLENGE_ACTION = "playground-run";
+declare function canonicalPlaygroundIp(value: string | null | undefined): string | null;
+/** Only Vercel's overwritten header is authoritative in this deployment, never generic XFF. */
+declare function playgroundProxyIp(headers: {
+    get(name: string): string | null;
+}, environment: {
+    VERCEL?: string;
+}): string | null;
+declare function playgroundRequestDigest(body: unknown, visitor: string, key: string): string;
+declare function signPlaygroundIngress(ipValue: string, digest: string, secret: string, now?: number): string | null;
+declare function verifyPlaygroundIngress(token: string | undefined, digest: string, secret: string, now?: number): string | null;
+/** Store only today's digest; query today and yesterday across the rolling 24-hour window. */
+declare function playgroundIpKeys(ip: string, secret: string, now: number): readonly [string, string];
+
+export { PLAYGROUND_CHALLENGE_ACTION, PLAYGROUND_CHALLENGE_HEADER, PLAYGROUND_INGRESS_HEADER, PLAYGROUND_INGRESS_SECRET_KEY, canonicalPlaygroundIp, playgroundIpKeys, playgroundProxyIp, playgroundRequestDigest, signPlaygroundIngress, verifyPlaygroundIngress };

package/dist/playground-ingress.js

@@ -0,0 +1,62 @@
+// src/playground-ingress.ts
+import { createHash, createHmac, timingSafeEqual } from "crypto";
+import { isIP } from "net";
+var PLAYGROUND_INGRESS_HEADER = "x-playground-ingress";
+var PLAYGROUND_INGRESS_SECRET_KEY = "ABLOH_PLAYGROUND_INGRESS_SECRET";
+var PLAYGROUND_CHALLENGE_HEADER = "x-playground-challenge";
+var PLAYGROUND_CHALLENGE_ACTION = "playground-run";
+var DAY_MS = 864e5;
+var MAX_AGE_MS = 6e4;
+function canonicalPlaygroundIp(value) {
+  if (!value || !isIP(value) || value.includes("%")) return null;
+  if (isIP(value) === 4) return value;
+  const canonical = new URL(`http://[${value}]/`).hostname.slice(1, -1);
+  const mapped = /^::ffff:([0-9a-f]+):([0-9a-f]+)$/u.exec(canonical);
+  if (!mapped) return canonical;
+  const high = parseInt(mapped[1], 16), low = parseInt(mapped[2], 16);
+  return `${high >>> 8}.${high & 255}.${low >>> 8}.${low & 255}`;
+}
+function playgroundProxyIp(headers, environment) {
+  return environment.VERCEL === "1" ? canonicalPlaygroundIp(headers.get("x-vercel-forwarded-for")) : null;
+}
+function playgroundRequestDigest(body, visitor, key) {
+  return createHash("sha256").update(JSON.stringify(["playground-new-run-v1", visitor, key, body])).digest("hex");
+}
+var mac = (key, text) => createHmac("sha256", key).update(text).digest("base64url");
+function signPlaygroundIngress(ipValue, digest, secret, now = Date.now()) {
+  const ip = canonicalPlaygroundIp(ipValue);
+  if (!ip || secret.length < 32) return null;
+  const payload = Buffer.from(JSON.stringify({ ip, digest, at: now })).toString("base64url");
+  return `${payload}.${mac(secret, payload)}`;
+}
+function verifyPlaygroundIngress(token, digest, secret, now = Date.now()) {
+  if (!token || token.length > 1024 || secret.length < 32) return null;
+  const [payload, signature, extra] = token.split(".");
+  if (!payload || !signature || extra !== void 0) return null;
+  const expected = Buffer.from(mac(secret, payload)), actual = Buffer.from(signature);
+  if (expected.length !== actual.length || !timingSafeEqual(expected, actual)) return null;
+  try {
+    const value = JSON.parse(Buffer.from(payload, "base64url").toString("utf8"));
+    if (value.digest !== digest || !Number.isSafeInteger(value.at) || value.at > now + 5e3 || now - value.at > MAX_AGE_MS) return null;
+    return canonicalPlaygroundIp(value.ip);
+  } catch {
+    return null;
+  }
+}
+function playgroundIpKeys(ip, secret, now) {
+  const epoch = Math.floor(now / DAY_MS);
+  const key = (day) => mac(mac(secret, `playground-ip-day:${day}`), ip);
+  return [key(epoch), key(epoch - 1)];
+}
+export {
+  PLAYGROUND_CHALLENGE_ACTION,
+  PLAYGROUND_CHALLENGE_HEADER,
+  PLAYGROUND_INGRESS_HEADER,
+  PLAYGROUND_INGRESS_SECRET_KEY,
+  canonicalPlaygroundIp,
+  playgroundIpKeys,
+  playgroundProxyIp,
+  playgroundRequestDigest,
+  signPlaygroundIngress,
+  verifyPlaygroundIngress
+};