@afora/core 0.0.8 → 0.0.11

package/dist/core/auth/jwt.d.ts

@@ -0,0 +1,30 @@
+import type { Jwt, JwtOptions } from "./types/jwt.interface.js";
+/** `jwtOf` got options it cannot use, or its secret is missing; `details.reason` says what. */
+export declare const InvalidJwtOptions: import("../../index.js").DeclaredExceptionClass<{
+    readonly reason: string;
+}>;
+/**
+ * Why `options` cannot be the options of `jwtOf`, naming them `where`;
+ * `undefined` when they can. `extra` are other keys the caller accepts, and
+ * `described` is for options that `describe()` and `afora.json` show, where
+ * the secret must be named by its environment variable, never written.
+ */
+export declare function jwtOptionsIssue(options: unknown, where: string, extra?: readonly string[], described?: boolean): string | undefined;
+/**
+ * Signs and verifies JSON Web Tokens with a shared secret (HMAC), on Web
+ * Crypto, so it runs on Bun, Node and Workers alike:
+ *
+ * ```ts
+ * const jwt = jwtOf({ secret: { env: "JWT_SECRET" }, issuer: "blog" });
+ * const token = await jwt.sign({ subject: user.id, scopes: ["posts:write"] });
+ * const principal = await jwt.verify(token); // { subject, scopes, claims? }
+ * hono(options, { authenticator: jwt.authenticator() });
+ * ```
+ *
+ * A token is refused (`Unauthenticated`) when it is malformed, signed with
+ * another algorithm or secret, expired, not yet valid, of another issuer,
+ * audience or use, or has no subject. Throws `InvalidJwtOptions` for options
+ * it cannot use, and when the secret of `{ env }` is missing or shorter than
+ * 32 characters, on the first token.
+ */
+export declare function jwtOf(options: JwtOptions): Jwt;

package/dist/core/auth/jwt.js

@@ -0,0 +1,200 @@
+import { ExceptionLayers } from "../exception/enums/exception-layers.js";
+import { exceptionOf } from "../exception/exception.js";
+import { Unauthenticated } from "../output/exceptions.js";
+export const InvalidJwtOptions = exceptionOf({
+  layer: ExceptionLayers.Output,
+  name: "InvalidJwtOptions",
+  message: ({ reason }) => reason
+});
+const HASHES = {
+  HS256: "SHA-256",
+  HS384: "SHA-384",
+  HS512: "SHA-512"
+};
+const MIN_SECRET = 32;
+const DEFAULT_EXPIRES_IN = 900;
+const REGISTERED = new Set([
+  "sub",
+  "scope",
+  "iat",
+  "exp",
+  "nbf",
+  "iss",
+  "aud",
+  "use"
+]);
+const encoder = new TextEncoder;
+const decoder = new TextDecoder;
+function base64url(bytes) {
+  let binary = "";
+  for (const byte of bytes)
+    binary += String.fromCharCode(byte);
+  return btoa(binary).replaceAll("+", "-").replaceAll("/", "_").replaceAll("=", "");
+}
+function bytesOf(text) {
+  if (!/^[A-Za-z0-9_-]*$/.test(text))
+    return;
+  try {
+    const binary = atob(text.replaceAll("-", "+").replaceAll("_", "/"));
+    const bytes = new Uint8Array(binary.length);
+    for (let i = 0;i < binary.length; i++)
+      bytes[i] = binary.charCodeAt(i);
+    return bytes;
+  } catch {
+    return;
+  }
+}
+function jsonOf(part) {
+  const bytes = bytesOf(part);
+  if (!bytes)
+    return;
+  try {
+    const value = JSON.parse(decoder.decode(bytes));
+    return typeof value === "object" && value !== null && !Array.isArray(value) ? value : undefined;
+  } catch {
+    return;
+  }
+}
+export function jwtOptionsIssue(options, where, extra = [], described = false) {
+  if (typeof options !== "object" || options === null || Array.isArray(options)) {
+    return `Expected ${where} to be { secret, issuer?, audience?, expiresIn?, algorithm? }.`;
+  }
+  const given = options;
+  const known = [
+    "secret",
+    "issuer",
+    "audience",
+    "expiresIn",
+    "algorithm",
+    ...extra
+  ];
+  for (const key of Object.keys(given)) {
+    if (!known.includes(key))
+      return `${where} has no option "${key}".`;
+  }
+  const { secret, issuer, audience, expiresIn, algorithm } = given;
+  const named = typeof secret === "object" && secret !== null && !Array.isArray(secret) ? secret : undefined;
+  if (named ? Object.keys(named).join() !== "env" || typeof named.env !== "string" || named.env === "" : typeof secret !== "string") {
+    return `Expected ${where}.secret to be the secret or { "env": "NAME" }.`;
+  }
+  if (described && !named) {
+    return `Expected ${where}.secret to be { "env": "NAME" }: these options are described, so the secret is named, not written.`;
+  }
+  if (typeof secret === "string" && secret.length < MIN_SECRET) {
+    return `Expected ${where}.secret to have at least ${MIN_SECRET} characters.`;
+  }
+  for (const [key, value] of [
+    ["issuer", issuer],
+    ["audience", audience]
+  ]) {
+    if (value !== undefined && (typeof value !== "string" || value === "")) {
+      return `Expected ${where}.${key} to be a non-empty string.`;
+    }
+  }
+  if (expiresIn !== undefined && (!Number.isInteger(expiresIn) || expiresIn <= 0)) {
+    return `Expected ${where}.expiresIn to be a whole number of seconds above 0.`;
+  }
+  if (algorithm !== undefined && !Object.hasOwn(HASHES, algorithm)) {
+    return `Expected ${where}.algorithm to be one of ${Object.keys(HASHES).join(", ")}.`;
+  }
+  return;
+}
+export function jwtOf(options) {
+  const issue = jwtOptionsIssue(options, "jwtOf");
+  if (issue) {
+    throw new InvalidJwtOptions({
+      source: "jwtOf",
+      details: { reason: issue }
+    });
+  }
+  const algorithm = options.algorithm ?? "HS256";
+  const lifetime = options.expiresIn ?? DEFAULT_EXPIRES_IN;
+  const header = base64url(encoder.encode(JSON.stringify({ alg: algorithm, typ: "JWT" })));
+  let imported;
+  const keyOf = () => {
+    if (imported)
+      return imported;
+    let secret;
+    if (typeof options.secret === "string")
+      secret = options.secret;
+    else {
+      const name = options.secret.env;
+      secret = globalThis.process?.env?.[name];
+      if (typeof secret !== "string" || secret.length < MIN_SECRET) {
+        throw new InvalidJwtOptions({
+          source: "jwtOf",
+          details: {
+            reason: `The environment variable ${name} must hold a secret of at least ${MIN_SECRET} characters.`
+          }
+        });
+      }
+    }
+    imported = crypto.subtle.importKey("raw", encoder.encode(secret), { name: "HMAC", hash: HASHES[algorithm] }, false, ["sign", "verify"]);
+    return imported;
+  };
+  const refused = () => {
+    throw new Unauthenticated({ source: "jwt" });
+  };
+  const jwt = {
+    async sign(subject, token = {}) {
+      const now = Math.floor(Date.now() / 1000);
+      const payload = {
+        ...subject.claims ?? {},
+        sub: subject.subject,
+        scope: (subject.scopes ?? []).join(" "),
+        iat: now,
+        exp: now + (token.expiresIn ?? lifetime),
+        ...options.issuer === undefined ? {} : { iss: options.issuer },
+        ...options.audience === undefined ? {} : { aud: options.audience },
+        ...token.use === undefined ? {} : { use: token.use }
+      };
+      const signing = `${header}.${base64url(encoder.encode(JSON.stringify(payload)))}`;
+      const signature = await crypto.subtle.sign("HMAC", await keyOf(), encoder.encode(signing));
+      return `${signing}.${base64url(new Uint8Array(signature))}`;
+    },
+    async verify(token, expected = {}) {
+      if (typeof token !== "string")
+        return refused();
+      const parts = token.split(".");
+      if (parts.length !== 3)
+        return refused();
+      const [head, body, sign] = parts;
+      if (jsonOf(head)?.alg !== algorithm)
+        return refused();
+      const signature = bytesOf(sign);
+      if (!signature)
+        return refused();
+      const valid = await crypto.subtle.verify("HMAC", await keyOf(), signature, encoder.encode(`${head}.${body}`));
+      const payload = valid ? jsonOf(body) : undefined;
+      if (!payload)
+        return refused();
+      const now = Math.floor(Date.now() / 1000);
+      const { sub, scope, exp, nbf, iss, aud, use } = payload;
+      if (typeof sub !== "string" || sub === "" || typeof exp !== "number" || exp <= now || nbf !== undefined && (typeof nbf !== "number" || nbf > now) || options.issuer !== undefined && iss !== options.issuer || options.audience !== undefined && aud !== options.audience && !(Array.isArray(aud) && aud.includes(options.audience)) || use !== expected.use) {
+        return refused();
+      }
+      const claims = {};
+      for (const [key, value] of Object.entries(payload)) {
+        if (!REGISTERED.has(key))
+          claims[key] = value;
+      }
+      return {
+        subject: sub,
+        scopes: typeof scope === "string" && scope !== "" ? scope.split(" ") : [],
+        ...Object.keys(claims).length > 0 ? { claims } : {}
+      };
+    },
+    authenticator(reading = {}) {
+      const header = (reading.header ?? "authorization").toLowerCase();
+      const { cookie } = reading;
+      return async (request) => {
+        const sent = request.header(header);
+        const token = sent !== undefined ? sent.replace(/^Bearer +/i, "").trim() : cookie !== undefined ? request.cookie(cookie) : undefined;
+        if (token === undefined || token === "")
+          return null;
+        return jwt.verify(token);
+      };
+    }
+  };
+  return Object.freeze(jwt);
+}

package/dist/core/auth/types/jwt.interface.d.ts

@@ -0,0 +1,74 @@
+import type { Authenticator } from "../../output/types/http.interface.js";
+import type { Principal } from "../../use-case/types/access.interface.js";
+/** The algorithms `jwtOf` signs and verifies with: HMAC with a shared secret. */
+export type JwtAlgorithm = "HS256" | "HS384" | "HS512";
+/** The options of `jwtOf`. JSON, so they can live in the options of a sink. */
+export interface JwtOptions {
+    /**
+     * The secret tokens are signed with: the text itself, or the name of the
+     * environment variable that holds it (`{ env: "JWT_SECRET" }`), read when
+     * the first token is signed or verified. At least 32 characters.
+     */
+    readonly secret: string | {
+        readonly env: string;
+    };
+    /** The `iss` claim: set when signing, required when verifying. */
+    readonly issuer?: string;
+    /** The `aud` claim: set when signing, required when verifying. */
+    readonly audience?: string;
+    /**
+     * The seconds a token lives.
+     *
+     * @default 900
+     */
+    readonly expiresIn?: number;
+    /**
+     * The algorithm the tokens are signed and verified with.
+     *
+     * @default "HS256"
+     */
+    readonly algorithm?: JwtAlgorithm;
+}
+/** What a token is signed for. */
+export interface JwtSubject {
+    readonly subject: string;
+    readonly scopes?: readonly string[];
+    readonly claims?: Principal["claims"];
+}
+/** What changes for one token. */
+export interface JwtTokenOptions {
+    /** The seconds this token lives, instead of the `expiresIn` of the options. */
+    readonly expiresIn?: number;
+    /**
+     * What the token is for, e.g. `"refresh"`: kept in its `use` claim, and a
+     * token verifies only for the use it was signed for (none by default), so
+     * a refresh token is not accepted as an access token.
+     */
+    readonly use?: string;
+}
+/** Signs and verifies the tokens of one secret (see `jwtOf`). */
+export interface Jwt {
+    /** A signed token for `subject`: `sub`, `scope` (the scopes, space separated), `iat`, `exp` and the claims. */
+    sign(subject: JwtSubject, options?: JwtTokenOptions): Promise<string>;
+    /** The caller a token was signed for. Rejects with `Unauthenticated` for a token it does not accept. */
+    verify(token: string, options?: Pick<JwtTokenOptions, "use">): Promise<Principal>;
+    /**
+     * An authenticator that reads the token from the `authorization` header
+     * (`Bearer <token>`; another header with `header`) and, with `cookie`,
+     * from that cookie when the header is absent. No token is an anonymous
+     * caller; one that does not verify is refused.
+     */
+    authenticator(options?: {
+        readonly header?: string;
+        readonly cookie?: string;
+    }): Authenticator;
+}
+/**
+ * The options of `jwtOf` where they are described (`describe()`,
+ * `afora.json`): the secret is named by its environment variable.
+ */
+export interface DescribedJwtOptions extends Omit<JwtOptions, "secret"> {
+    readonly secret: {
+        readonly env: string;
+    };
+}

package/dist/core/blueprint/blueprint-plugin.js

@@ -0,0 +1,7 @@
+export function blueprintPluginOf(name, properties, factories = {}) {
+  return Object.freeze({
+    name,
+    properties: Object.freeze({ ...properties }),
+    factories: Object.freeze({ ...factories })
+  });
+}

package/dist/core/blueprint/blueprint.js

@@ -0,0 +1,146 @@
+import { Type } from "typebox";
+import { collectionParserOf } from "../parse/parse.js";
+import { isProperty } from "../property/is-property.js";
+import { propertyOf } from "../property/property.js";
+import { rawTypeOf, schemaOf } from "../schema/schema.js";
+import { withStandard } from "../standard/standard.js";
+import { Kind } from "../symbols/kind.js";
+import { callableOf, fieldOf } from "./callable.js";
+import {
+  ReservedBlueprintKey,
+  UndeclaredBlueprintProperty
+} from "./exceptions.js";
+import { isBlueprint } from "./is-blueprint.js";
+import { isBlueprintList, listOf } from "./list.js";
+import { optionalOf } from "./optional.js";
+import { recordFieldOf } from "./record-field.js";
+import { blueprintOfVariant, isBlueprintVariant, variantOf } from "./variant.js";
+export function blueprintBuilderOf(...base) {
+  return (sourcesOrDefine, maybeDefine) => {
+    const [sources, define] = typeof sourcesOrDefine === "function" ? [[], sourcesOrDefine] : [
+      sourcesOrDefine,
+      maybeDefine
+    ];
+    const all = [...base, ...sources];
+    return create(all.flatMap((source) => isBlueprint(source) ? source.plugins : [source]), { ...define(contextOf(all)) });
+  };
+}
+export function blueprintFromProperties(plugins, properties) {
+  return create(plugins, { ...properties });
+}
+function create(plugins, properties) {
+  const shape = {};
+  for (const [key, field] of Object.entries(properties)) {
+    properties[key] = fieldOf(field);
+    shape[key] = schemaOfField(key, properties[key]);
+  }
+  const SchemaConstructor = schemaOf("blueprint", Type.Object(shape));
+  const safeParse = collectionParserOf(properties, "blueprint");
+  const blueprint = {
+    [Kind]: "blueprint",
+    plugins: Object.freeze([...new Set(plugins)]),
+    properties: Object.freeze(properties),
+    schema: new SchemaConstructor,
+    optional: false,
+    safeParse,
+    join: (...others) => create([blueprint, ...others].flatMap((source) => source.plugins), Object.assign({}, ...[blueprint, ...others].map((source) => source.properties)))
+  };
+  return Object.freeze(withStandard(blueprint, safeParse));
+}
+const HELPERS = { listOf, optionalOf, propertyOf, variantOf };
+const RESERVED_KEYS = ["optional", "list", ...Object.keys(HELPERS)];
+function lazyMirror(keys, make) {
+  const fields = {};
+  for (const key of keys) {
+    let field;
+    Object.defineProperty(fields, key, {
+      get: () => {
+        field ??= make(key);
+        return field;
+      },
+      enumerable: true
+    });
+  }
+  return fields;
+}
+function contextOf(sources) {
+  for (const key of RESERVED_KEYS) {
+    const reserving = sources.find((source) => Object.hasOwn(source.properties, key));
+    if (reserving) {
+      throw new ReservedBlueprintKey({
+        source: isBlueprint(reserving) ? "blueprint" : reserving.name,
+        details: { key }
+      });
+    }
+  }
+  const factories = Object.assign({}, ...sources.map((source) => isBlueprint(source) ? {} : source.factories ?? {}));
+  for (const key of RESERVED_KEYS) {
+    if (Object.hasOwn(factories, key)) {
+      const reserving = sources.find((source) => !isBlueprint(source) && Object.hasOwn(source.factories ?? {}, key));
+      throw new ReservedBlueprintKey({
+        source: reserving.name,
+        details: { key }
+      });
+    }
+  }
+  const available = Object.assign({}, ...sources.map((source) => source.properties));
+  for (const key of Object.keys(factories))
+    delete available[key];
+  const mirror = (fields, map) => Object.fromEntries(Object.entries(fields).map(([key, field]) => [key, map(field)]));
+  const callable = (field) => isProperty(field) ? callableOf(field) : field;
+  const keys = Object.keys(available);
+  const list = lazyMirror(keys, (key) => listOf(available[key]));
+  const optional = lazyMirror(keys, (key) => callable(optionalOf(available[key])));
+  const listOptional = Object.freeze(lazyMirror(keys, (key) => optionalOf(list[key])));
+  Object.defineProperty(list, "optional", {
+    value: listOptional,
+    enumerable: true
+  });
+  return Object.freeze({
+    ...mirror(available, callable),
+    ...factories,
+    ...HELPERS,
+    optional: Object.freeze(optional),
+    list: Object.freeze(list)
+  });
+}
+function schemaOfField(key, field) {
+  if (isBlueprintList(field)) {
+    const { item, minItems, maxItems } = field;
+    const schema = Type.Array(schemaOfField(key, item), {
+      ...minItems === undefined ? {} : { minItems },
+      ...maxItems === undefined ? {} : { maxItems }
+    });
+    return field.optional ? Type.Optional(schema) : schema;
+  }
+  if (isBlueprint(field)) {
+    const schema = rawTypeOf(field.schema);
+    return field.optional ? Type.Optional(schema) : schema;
+  }
+  if (isBlueprintVariant(field)) {
+    const schema = Type.Union(Object.entries(field.variants).map(([tag, variant]) => {
+      const object = rawTypeOf(blueprintOfVariant(variant).schema);
+      return {
+        ...object,
+        properties: {
+          [field.key]: Type.Literal(tag),
+          ...object.properties
+        },
+        required: [field.key, ...object.required ?? []]
+      };
+    }));
+    return field.optional ? Type.Optional(schema) : schema;
+  }
+  const record = recordFieldOf(field);
+  if (record) {
+    const schema = rawTypeOf(record.record.blueprint.schema);
+    return record.optional ? Type.Optional(schema) : schema;
+  }
+  if (isProperty(field)) {
+    return rawTypeOf(field.type.schema);
+  }
+  throw new UndeclaredBlueprintProperty({
+    source: "blueprint",
+    details: { key }
+  });
+}

package/dist/core/blueprint/callable.js

@@ -0,0 +1,13 @@
+import { isProperty } from "../property/is-property.js";
+import { refinePropertyOf } from "../property/refine.js";
+const targets = new WeakMap;
+export function callableOf(Property) {
+  const callable = new Proxy(Property, {
+    apply: (target, _this, [options]) => refinePropertyOf(target, options ?? {})
+  });
+  targets.set(callable, Property);
+  return callable;
+}
+export function fieldOf(field) {
+  return (isProperty(field) ? targets.get(field) : undefined) ?? field;
+}

package/dist/core/blueprint/exceptions.d.ts

@@ -2,6 +2,11 @@
 export declare const ReservedBlueprintKey: import("../../index.js").DeclaredExceptionClass<{
     readonly key: string;
 }>;
+/** `variantOf` was given something it cannot make a field of; `reason` says what. */
+export declare const InvalidBlueprintVariant: import("../../index.js").DeclaredExceptionClass<{
+    readonly key: string;
+    readonly reason: string;
+}>;
 /** A blueprint picks a key that no plugin provides. */
 export declare const UndeclaredBlueprintProperty: import("../../index.js").DeclaredExceptionClass<{
     readonly key: string;

package/dist/core/blueprint/exceptions.js

@@ -0,0 +1,20 @@
+import { ExceptionLayers } from "../exception/enums/exception-layers.js";
+import { exceptionOf } from "../exception/exception.js";
+export const ReservedBlueprintKey = exceptionOf({
+  layer: ExceptionLayers.Blueprint,
+  name: "ReservedBlueprintKey",
+  message: ({ key }) => `"${key}" is reserved and cannot be a plugin property.`
+});
+export const InvalidBlueprintVariant = exceptionOf({
+  layer: ExceptionLayers.Blueprint,
+  name: "InvalidBlueprintVariant",
+  message: ({
+    key,
+    reason
+  }) => `The variant field of key "${key}" cannot be declared: ${reason}.`
+});
+export const UndeclaredBlueprintProperty = exceptionOf({
+  layer: ExceptionLayers.Blueprint,
+  name: "UndeclaredBlueprintProperty",
+  message: ({ key }) => `Property "${key}" of the blueprint is not declared.`
+});

package/dist/core/blueprint/is-blueprint.js

@@ -0,0 +1,4 @@
+import { Kind } from "../symbols/kind.js";
+export function isBlueprint(value) {
+  return typeof value === "object" && value !== null && value[Kind] === "blueprint";
+}

package/dist/core/blueprint/list.js

@@ -0,0 +1,19 @@
+import { parseField } from "../parse/parse.js";
+import { withStandard } from "../standard/standard.js";
+import { Kind } from "../symbols/kind.js";
+import { fieldOf } from "./callable.js";
+export function listOf(item, { minItems, maxItems } = {}) {
+  return standardListOf({
+    [Kind]: "list",
+    item: fieldOf(item),
+    optional: false,
+    minItems,
+    maxItems
+  });
+}
+export function standardListOf(list) {
+  return Object.freeze(withStandard(list, (value) => parseField(list, value, [], "list")));
+}
+export function isBlueprintList(value) {
+  return typeof value === "object" && value !== null && value[Kind] === "list";
+}

package/dist/core/blueprint/optional.d.ts

@@ -1,6 +1,6 @@
 import type { OptionalProperty } from "../property/types/optional-property.type.js";
 import type { AnyPropertyConstructor } from "../property/types/property-collection.type.js";
-import type { AnyBlueprint, AnyBlueprintList, AnyRecordClass, BlueprintField, OptionalBlueprint, OptionalBlueprintList, OptionalRecord } from "./types/blueprint.interface.js";
+import type { AnyBlueprint, AnyBlueprintList, AnyBlueprintVariant, AnyRecordClass, BlueprintField, OptionalBlueprint, OptionalBlueprintList, OptionalBlueprintVariant, OptionalRecord } from "./types/blueprint.interface.js";
 /**
  * The version of `Property` that accepts `undefined`. Returns `Property` itself
  * when it is already optional, and the same class for the same `Property`.
@@ -13,6 +13,8 @@ export declare function optionalOf<Property extends AnyPropertyConstructor>(Prop
 export declare function optionalOf<Blueprint extends AnyBlueprint>(blueprint: Blueprint): OptionalBlueprint<Blueprint>;
 /** The version of `list` that, as a field of a blueprint, accepts `undefined`. */
 export declare function optionalOf<List extends AnyBlueprintList>(list: List): OptionalBlueprintList<List>;
+/** The version of `variant` that, as a field of a blueprint, accepts `undefined`. */
+export declare function optionalOf<Variant extends AnyBlueprintVariant>(variant: Variant): OptionalBlueprintVariant<Variant>;
 /**
  * The version of `record` that, as a field of a blueprint, accepts `undefined`
  * or an instance of `record`. Returns `record` itself when it is already optional.

package/dist/core/blueprint/optional.js

@@ -0,0 +1,69 @@
+import { Type } from "typebox";
+import { recordPropertyLineage } from "../property/lineage.js";
+import { derivePropertyOf } from "../property/refine.js";
+import { rawTypeOf, schemaOf } from "../schema/schema.js";
+import { withStandard } from "../standard/standard.js";
+import { Kind } from "../symbols/kind.js";
+import { fieldOf } from "./callable.js";
+import { isBlueprint } from "./is-blueprint.js";
+import { isBlueprintList, standardListOf } from "./list.js";
+import { isOptionalRecord, isRecordClass } from "./record-field.js";
+import { isBlueprintVariant, standardVariantOf } from "./variant.js";
+const cache = new WeakMap;
+export function optionalOf(given) {
+  const field = fieldOf(given);
+  const cached = cache.get(field);
+  if (cached)
+    return cached;
+  if (isOptionalRecord(field))
+    return field;
+  if (isRecordClass(field)) {
+    const optional = Object.freeze(withStandard({
+      [Kind]: "record",
+      record: field,
+      optional: true
+    }, (value) => value === undefined ? { value } : field.safeParse(value)));
+    cache.set(field, optional);
+    return optional;
+  }
+  if (isBlueprint(field)) {
+    if (field.optional)
+      return field;
+    const optional = {
+      ...field,
+      optional: true,
+      safeParse: (value) => value === undefined ? { value } : field.safeParse(value)
+    };
+    Object.freeze(withStandard(optional, (value) => optional.safeParse(value)));
+    cache.set(field, optional);
+    return optional;
+  }
+  if (isBlueprintList(field)) {
+    if (field.optional)
+      return field;
+    const optional = standardListOf({ ...field, optional: true });
+    cache.set(field, optional);
+    return optional;
+  }
+  if (isBlueprintVariant(field)) {
+    if (field.optional)
+      return field;
+    const optional = standardVariantOf({ ...field, optional: true });
+    cache.set(field, optional);
+    return optional;
+  }
+  const Property = field;
+  if (Property.type.optional)
+    return Property;
+  const base = Property.type;
+  const SchemaConstructor = schemaOf(base.name, Type.Optional(rawTypeOf(base.schema)));
+  const type = {
+    ...base,
+    schema: new SchemaConstructor,
+    optional: true
+  };
+  const Optional = derivePropertyOf(Property, type);
+  recordPropertyLineage(Optional, { kind: "optional", base: Property });
+  cache.set(Property, Optional);
+  return Optional;
+}

package/dist/core/blueprint/record-field.js

@@ -0,0 +1,14 @@
+import { Kind } from "../symbols/kind.js";
+export function isRecordClass(value) {
+  return typeof value === "function" && value[Kind] === "record";
+}
+export function isOptionalRecord(value) {
+  return typeof value === "object" && value !== null && value[Kind] === "record";
+}
+export function recordFieldOf(field) {
+  if (isRecordClass(field))
+    return { record: field, optional: false };
+  if (isOptionalRecord(field))
+    return field;
+  return;
+}