@afora/core 0.0.9 → 0.0.12

package/dist/std/record-plugins.js

@@ -0,0 +1,73 @@
+import { recordPluginOf } from "../core/record/plugin.js";
+import { recordPluginCatalogOf } from "../core/record/plugin-catalog.js";
+import { recordOf } from "../core/record/record.js";
+import { blueprintOf } from "./blueprint.js";
+import { Password } from "./properties/password.js";
+const now = () => new Date().toISOString();
+
+export class PublishableRecord extends recordOf(blueprintOf((ctx) => ({ publishedAt: ctx.optional.dateTime }))) {
+  get isPublished() {
+    return this.publishedAt !== undefined;
+  }
+  publish(at = now()) {
+    return this.set("publishedAt", at);
+  }
+  unpublish() {
+    return this.set("publishedAt", undefined);
+  }
+}
+export const Publishable = recordPluginOf("publishable", PublishableRecord, {
+  description: "A publication date, with publish, unpublish and isPublished."
+});
+
+export class ArchivableRecord extends recordOf(blueprintOf((ctx) => ({ archivedAt: ctx.optional.dateTime }))) {
+  get isArchived() {
+    return this.archivedAt !== undefined;
+  }
+  archive(at = now()) {
+    return this.set("archivedAt", at);
+  }
+  restore() {
+    return this.set("archivedAt", undefined);
+  }
+}
+export const Archivable = recordPluginOf("archivable", ArchivableRecord, {
+  description: "An archive date, with archive, restore and isArchived."
+});
+
+export class TaggableRecord extends recordOf(blueprintOf((ctx) => ({ tags: ctx.list.optional.string }))) {
+  hasTag(tag) {
+    return this.tags?.includes(tag) ?? false;
+  }
+  tag(...tags) {
+    return this.set("tags", [...new Set([...this.tags ?? [], ...tags])]);
+  }
+  untag(...tags) {
+    return this.set("tags", (this.tags ?? []).filter((tag) => !tags.includes(tag)));
+  }
+}
+export const Taggable = recordPluginOf("taggable", TaggableRecord, {
+  description: "A list of tags, with tag, untag and hasTag."
+});
+
+export class OwnableRecord extends recordOf(blueprintOf((ctx) => ({ ownerId: ctx.id }))) {
+  isOwnedBy(id) {
+    return this.ownerId === id.toLowerCase();
+  }
+  transferTo(id) {
+    return this.set("ownerId", id);
+  }
+}
+export const Ownable = recordPluginOf("ownable", OwnableRecord, {
+  description: "The id of the owner, with isOwnedBy and transferTo."
+});
+
+export class AuthenticatableRecord extends recordOf(blueprintOf((ctx) => ({ email: ctx.email, password: ctx.password })), { unique: ["email"], change: ["password"] }) {
+  verifyPassword(plain) {
+    return new Password(this.password).verify(plain);
+  }
+}
+export const Authenticatable = recordPluginOf("authenticatable", AuthenticatableRecord, {
+  description: "A unique email and a sensitive password hash, with change.password and verifyPassword."
+});
+export const StdRecordPlugins = recordPluginCatalogOf(Publishable, Archivable, Taggable, Ownable, Authenticatable);

package/dist/std/record.d.ts

@@ -1,6 +1,25 @@
 /**
  * A record of `blueprint`, e.g. `class User extends recordOf(UserBlueprint) {}`,
  * whose `options.plugins` picks from the standard plugins, as
- * `(ctx) => [ctx.publishable]`, or takes any plugin made by `recordPluginOf`.
+ * `(ctx) => [ctx.publishable]`, or takes any plugin made by {@link recordPluginOf}.
+ *
+ * @throws {@link ReservedRecordKey} when a key of the blueprint is a member of the record.
+ * @throws {@link UndeclaredRecordProperty} when `sensitive`, `unique` or `change` names a key the blueprint does not declare.
+ * @throws {@link InvalidRecordDeclaration} when `name` is not an identifier.
+ *
+ * @example
+ * ```ts
+ * import { blueprintOf, recordOf } from "@afora/core";
+ *
+ * class Account extends recordOf(
+ * 	blueprintOf((ctx) => ({ email: ctx.email, token: ctx.string })),
+ * 	{ sensitive: ["token"], change: ["email"] },
+ * ) {}
+ *
+ * const account = new Account({ email: "Ana@Example.com", token: "secret" });
+ * account.email; // "ana@example.com"
+ * account.change.email("ann@example.com"); // same as set("email", ...)
+ * JSON.stringify(account); // the token is masked
+ * ```
  */
 export declare const recordOf: import("../index.js").RecordBuilder<Omit<import("../core/record/types/plugin.interface.js").RecordPluginsByName<readonly [import("../index.js").IRecordPlugin<typeof import("./record-plugins.js").PublishableRecord, "publishable">, import("../index.js").IRecordPlugin<typeof import("./record-plugins.js").ArchivableRecord, "archivable">, import("../index.js").IRecordPlugin<typeof import("./record-plugins.js").TaggableRecord, "taggable">, import("../index.js").IRecordPlugin<typeof import("./record-plugins.js").OwnableRecord, "ownable">, import("../index.js").IRecordPlugin<typeof import("./record-plugins.js").AuthenticatableRecord, "authenticatable">]>, never> & Record<never, never>>;

package/dist/std/record.js

@@ -0,0 +1,3 @@
+import { recordBuilderOf } from "../core/record/record.js";
+import { StdRecordPlugins } from "./record-plugins.js";
+export const recordOf = recordBuilderOf(StdRecordPlugins);

package/dist/std/resource.js

@@ -0,0 +1,39 @@
+const ACTIONS = [
+  "create",
+  "get",
+  "list",
+  "update",
+  "delete"
+];
+function routeOf(action, path) {
+  switch (action) {
+    case "create":
+      return { method: "post", path, status: 201 };
+    case "list":
+      return { method: "get", path };
+    case "get":
+      return { method: "get", path: `${path}/{id}` };
+    case "update":
+      return { method: "patch", path: `${path}/{id}` };
+    default:
+      return { method: "delete", path: `${path}/{id}` };
+  }
+}
+export function resourceOf(repository, options) {
+  const actions = options.actions ?? ACTIONS;
+  const { access } = options;
+  const byAction = access !== undefined && Object.keys(access).some((key) => ACTIONS.includes(key));
+  const accessOf = (action) => byAction ? access[action] : access;
+  return (ctx) => {
+    const useCases = {};
+    for (const action of actions) {
+      const declared = accessOf(action);
+      const make = ctx[action];
+      useCases[action] = make(repository, {
+        route: routeOf(action, options.path),
+        ...declared === undefined ? {} : { access: declared }
+      });
+    }
+    return useCases;
+  };
+}

package/dist/std/runtime.js

@@ -0,0 +1,193 @@
+import { ExceptionLayers } from "../core/exception/enums/exception-layers.js";
+import { exceptionOf } from "../core/exception/exception.js";
+import { markExported } from "../core/exception/exported.js";
+export const PasswordHasherRequired = exceptionOf({
+  layer: ExceptionLayers.Property,
+  name: "PasswordHasherRequired",
+  message: "No password hasher is available: this runtime has neither Bun.password nor native argon2 (node:crypto, Node >= 24.7). Call configure({ hasher }) with your own PasswordHasher."
+});
+export const SyncVerifyUnsupported = exceptionOf({
+  layer: ExceptionLayers.Property,
+  name: "SyncVerifyUnsupported",
+  message: "The configured password hasher has no verifySync. Use verify, or configure a hasher that provides verifySync."
+});
+export const UnsupportedPasswordHash = exceptionOf({
+  layer: ExceptionLayers.Property,
+  name: "UnsupportedPasswordHash",
+  message: ({ version }) => `The password hash uses argon2 version ${version}, but native argon2 (node:crypto) only derives version ${ARGON2_VERSION}. Verify it with Bun.password or configure({ hasher }).`
+});
+markExported(PasswordHasherRequired, SyncVerifyUnsupported);
+const ARGON2_VERSION = 19;
+const ARGON2_PARAMS = {
+  memory: 65536,
+  passes: 2,
+  parallelism: 1,
+  tagLength: 32,
+  saltLength: 32,
+  version: ARGON2_VERSION
+};
+export const toBase64 = (bytes) => btoa(Array.from(bytes, (byte) => String.fromCharCode(byte)).join("")).replace(/=+$/, "");
+export const fromBase64 = (text) => Uint8Array.from(atob(text), (char) => char.charCodeAt(0));
+export function encodePhc(salt, tag) {
+  const { memory, passes, parallelism, version } = ARGON2_PARAMS;
+  return `$argon2id$v=${version}$m=${memory},t=${passes},p=${parallelism}$${toBase64(salt)}$${toBase64(tag)}`;
+}
+const PHC = /^\$argon2id\$v=(\d+)\$m=(\d+),t=(\d+),p=(\d+)\$([A-Za-z0-9+/]+)\$([A-Za-z0-9+/]+)$/;
+export function decodePhc(phc) {
+  const match = PHC.exec(phc);
+  if (!match)
+    return;
+  return {
+    version: Number(match[1]),
+    memory: Number(match[2]),
+    passes: Number(match[3]),
+    parallelism: Number(match[4]),
+    salt: fromBase64(match[5]),
+    tag: fromBase64(match[6])
+  };
+}
+export function nodeHasherOf(crypto) {
+  const { argon2, argon2Sync, randomBytes, timingSafeEqual } = crypto;
+  if (!argon2 || !argon2Sync || !randomBytes || !timingSafeEqual) {
+    return;
+  }
+  const derive = (parameters) => new Promise((resolve, reject) => {
+    argon2("argon2id", parameters, (error, key) => error ? reject(error) : resolve(key));
+  });
+  const parametersOf = (plain, parsed) => ({
+    message: plain,
+    nonce: parsed.salt,
+    parallelism: parsed.parallelism,
+    tagLength: parsed.tag.length,
+    memory: parsed.memory,
+    passes: parsed.passes
+  });
+  const decode = (hash) => {
+    const parsed = decodePhc(hash);
+    if (parsed && parsed.version !== ARGON2_VERSION) {
+      throw new UnsupportedPasswordHash({
+        source: "password",
+        details: { version: parsed.version }
+      });
+    }
+    return parsed;
+  };
+  const matches = (tag, expected) => tag.length === expected.length && timingSafeEqual(tag, expected);
+  return {
+    async hash(plain) {
+      const salt = randomBytes(ARGON2_PARAMS.saltLength);
+      const tag = await derive({
+        message: plain,
+        nonce: salt,
+        parallelism: ARGON2_PARAMS.parallelism,
+        tagLength: ARGON2_PARAMS.tagLength,
+        memory: ARGON2_PARAMS.memory,
+        passes: ARGON2_PARAMS.passes
+      });
+      return encodePhc(salt, tag);
+    },
+    async verify(plain, hash) {
+      const parsed = decode(hash);
+      if (!parsed)
+        return false;
+      return matches(await derive(parametersOf(plain, parsed)), parsed.tag);
+    },
+    verifySync(plain, hash) {
+      const parsed = decode(hash);
+      if (!parsed)
+        return false;
+      const tag = argon2Sync("argon2id", parametersOf(plain, parsed));
+      return matches(tag, parsed.tag);
+    }
+  };
+}
+function bunHasherOf(password) {
+  return {
+    hash: (plain) => password.hash(plain, { algorithm: "argon2id" }),
+    verify: (plain, hash) => password.verify(plain, hash),
+    verifySync: (plain, hash) => password.verifySync(plain, hash)
+  };
+}
+function missingHasher() {
+  return {
+    hash: () => Promise.reject(new PasswordHasherRequired({ source: "password" })),
+    verify: () => Promise.reject(new PasswordHasherRequired({ source: "password" })),
+    verifySync: () => {
+      throw new PasswordHasherRequired({ source: "password" });
+    }
+  };
+}
+export function defaultHasherOf(environment) {
+  if (environment.bun?.password) {
+    return bunHasherOf(environment.bun.password);
+  }
+  const node = environment.crypto && nodeHasherOf(environment.crypto);
+  return node ?? missingHasher();
+}
+let lastTimestamp = 0;
+let sequence = 0;
+const HEX = Array.from({ length: 256 }, (_, byte) => byte.toString(16).padStart(2, "0"));
+const RANDOM_PER_ID = 10;
+const randomPool = new Uint8Array(RANDOM_PER_ID * 64);
+let randomAt = randomPool.length;
+export function uuidv7(now = Date.now()) {
+  if (randomAt === randomPool.length) {
+    globalThis.crypto.getRandomValues(randomPool);
+    randomAt = 0;
+  }
+  const at = randomAt;
+  randomAt += RANDOM_PER_ID;
+  const random = randomPool;
+  const start = random[at + 8] << 8 | random[at + 9];
+  if (now > lastTimestamp) {
+    lastTimestamp = now;
+    sequence = start & 2047;
+  } else if (sequence < 4095) {
+    sequence++;
+  } else {
+    lastTimestamp++;
+    sequence = start & 2047;
+  }
+  const high = Math.floor(lastTimestamp / 2 ** 32);
+  const low = lastTimestamp % 2 ** 32;
+  const hex = (byte) => HEX[byte & 255];
+  return hex(high >>> 8) + hex(high) + hex(low >>> 24) + hex(low >>> 16) + "-" + hex(low >>> 8) + hex(low) + "-" + hex(112 | sequence >>> 8) + hex(sequence) + "-" + hex(random[at] & 63 | 128) + hex(random[at + 1]) + "-" + hex(random[at + 2]) + hex(random[at + 3]) + hex(random[at + 4]) + hex(random[at + 5]) + hex(random[at + 6]) + hex(random[at + 7]);
+}
+let hasher;
+const defaultIdGenerator = () => uuidv7();
+let idGenerator = defaultIdGenerator;
+export function configure(services) {
+  if (services.hasher)
+    hasher = services.hasher;
+  if (services.idGenerator)
+    idGenerator = services.idGenerator;
+}
+export function resetRuntime() {
+  hasher = undefined;
+  idGenerator = defaultIdGenerator;
+  lastTimestamp = 0;
+  sequence = 0;
+}
+function nodeCryptoOf() {
+  const process = globalThis.process;
+  return process?.getBuiltinModule?.("node:crypto");
+}
+export function currentHasher() {
+  hasher ??= defaultHasherOf({
+    bun: globalThis.Bun,
+    crypto: nodeCryptoOf()
+  });
+  return hasher;
+}
+export function makesDefaultIds() {
+  return idGenerator === defaultIdGenerator;
+}
+export function generateId() {
+  return idGenerator();
+}
+export function verifySyncWithCurrent(plain, hash) {
+  const current = currentHasher();
+  if (!current.verifySync)
+    throw new SyncVerifyUnsupported({ source: "password" });
+  return current.verifySync(plain, hash);
+}

package/dist/std/stages.js

@@ -0,0 +1,4 @@
+import { openapi } from "../core/output/openapi-sink.js";
+import { select } from "../core/output/select.js";
+import { stageCatalogOf } from "../core/output/stage.js";
+export const StdStages = stageCatalogOf(select, openapi);

package/dist/std/use-cases/auth.js

@@ -0,0 +1,193 @@
+import { jwtOf, jwtOptionsIssue } from "../../core/auth/jwt.js";
+import { outputValueOf } from "../../core/output/problem.js";
+import {
+  UseCaseEntityConflict,
+  UseCaseInvalidCredentials
+} from "../../core/use-case/exceptions.js";
+import { useCasePluginOf } from "../../core/use-case/plugin.js";
+import { StringProperty } from "../properties/primitives.js";
+import { createCompilation } from "./crud.js";
+import {
+  asOf,
+  checkOptions,
+  errorOf,
+  fields,
+  metaOf
+} from "./shared.js";
+const TOKEN_KEYS = ["refresh", "scopes", "scopesFrom", "claims"];
+const isTexts = (value) => Array.isArray(value) && value.every((item) => typeof item === "string");
+function tokensOf(target, options) {
+  const given = options.token;
+  if (given === undefined)
+    return;
+  const bad = jwtOptionsIssue(given, "the option token", TOKEN_KEYS, true);
+  if (bad)
+    return target.unavailable(bad);
+  const { refresh, scopes, scopesFrom, claims, ...jwtOptions } = given;
+  if (refresh !== undefined && (typeof refresh !== "object" || refresh === null || Object.keys(refresh).join() !== "expiresIn" || !Number.isInteger(refresh.expiresIn) || refresh.expiresIn <= 0)) {
+    return target.unavailable("the option token.refresh must be { expiresIn }, a whole number of seconds above 0");
+  }
+  if (scopes !== undefined && !isTexts(scopes)) {
+    return target.unavailable("the option token.scopes must be a list of scopes");
+  }
+  if (scopesFrom !== undefined)
+    target.field(scopesFrom);
+  if (claims !== undefined && (typeof claims !== "object" || claims === null || Array.isArray(claims))) {
+    return target.unavailable("the option token.claims must map claims to keys of the entity");
+  }
+  const claimKeys = Object.entries(claims ?? {});
+  for (const [, key] of claimKeys)
+    target.field(key);
+  const jwt = jwtOf(jwtOptions);
+  const issue = async (entity) => {
+    const held = scopesFrom === undefined ? [] : entity[scopesFrom];
+    const subject = {
+      subject: String(entity.id),
+      scopes: [...new Set([...scopes ?? [], ...isTexts(held) ? held : []])],
+      ...claimKeys.length > 0 ? {
+        claims: Object.fromEntries(claimKeys.map(([claim, key]) => [
+          claim,
+          outputValueOf(entity[key])
+        ]))
+      } : {}
+    };
+    return {
+      token: await jwt.sign(subject),
+      ...refresh ? {
+        refreshToken: await jwt.sign({ subject: subject.subject }, { expiresIn: refresh.expiresIn, use: "refresh" })
+      } : {}
+    };
+  };
+  const verifyRefresh = (token) => jwt.verify(token, { use: "refresh" });
+  return { issue, verifyRefresh, refresh: refresh !== undefined };
+}
+const authenticatable = (actions) => ({
+  requires: { actions, plugins: ["authenticatable"] }
+});
+export const register = useCasePluginOf("register", {
+  description: "Stores an authenticatable entity built from the input, its password given plain and stored as a hash, unless the email is taken.",
+  ...authenticatable(["findByEmail", "create"]),
+  compile: (target, options) => {
+    const conflict = errorOf(target, options, "conflict", UseCaseEntityConflict);
+    return createCompilation(target, options, "Register", (input) => [
+      {
+        find: "repository.findByEmail",
+        args: [`${input}.email`],
+        as: "existing"
+      },
+      { ensure: "absent", value: "$existing", error: conflict }
+    ], [conflict]);
+  }
+});
+export const login = useCasePluginOf("login", {
+  description: "Gives the authenticatable entity of an email when the password matches, with a token (and a refresh token) for it when the option token is given.",
+  ...authenticatable(["findByEmail"]),
+  compile: (target, options) => {
+    checkOptions(target, options, ["as", "token"]);
+    const tokens = tokensOf(target, options);
+    const invalid = errorOf(target, options, "invalid", UseCaseInvalidCredentials);
+    return {
+      ...metaOf(target, options, "Login"),
+      blueprint: fields(() => ({
+        email: target.field("email").field,
+        password: StringProperty
+      })),
+      response: fields(() => ({
+        [asOf(target, options)]: target.entity,
+        ...tokens ? { token: StringProperty } : {},
+        ...tokens?.refresh ? { refreshToken: StringProperty } : {}
+      })),
+      dependencies: { repository: target.repository },
+      errors: [invalid],
+      steps: [
+        { find: "repository.findByEmail", args: ["$input.email"], as: "item" },
+        { ensure: "exists", value: "$item", error: invalid },
+        {
+          invoke: "$item",
+          method: "verifyPassword",
+          args: ["$input.password"],
+          as: "matches"
+        },
+        { ensure: "true", value: "$matches", error: invalid },
+        ...tokens ? [
+          {
+            run: "issueTokens",
+            fn: tokens.issue,
+            args: ["$item"],
+            as: "tokens"
+          }
+        ] : [],
+        {
+          return: {
+            [asOf(target, options)]: "$item",
+            ...tokens ? { token: "$tokens.token" } : {},
+            ...tokens?.refresh ? { refreshToken: "$tokens.refreshToken" } : {}
+          }
+        }
+      ]
+    };
+  }
+});
+export const refresh = useCasePluginOf("refresh", {
+  description: "Exchanges a refresh token issued by login for a new token and a new refresh token, for the entity it names, if it still exists. Experimental.",
+  requires: { actions: ["findById"] },
+  compile: (target, options) => {
+    checkOptions(target, options, ["token"]);
+    const tokens = tokensOf(target, options);
+    if (!tokens?.refresh) {
+      return target.unavailable("it needs the option token with refresh, the same login was given");
+    }
+    const invalid = errorOf(target, options, "invalid", UseCaseInvalidCredentials);
+    return {
+      ...metaOf(target, options, "Refresh"),
+      blueprint: fields(() => ({ refreshToken: StringProperty })),
+      response: fields(() => ({
+        token: StringProperty,
+        refreshToken: StringProperty
+      })),
+      dependencies: { repository: target.repository },
+      errors: [invalid],
+      steps: [
+        {
+          run: "verifyRefreshToken",
+          fn: tokens.verifyRefresh,
+          args: ["$input.refreshToken"],
+          as: "caller"
+        },
+        {
+          find: "repository.findById",
+          args: ["$caller.subject"],
+          as: "item"
+        },
+        { ensure: "exists", value: "$item", error: invalid },
+        {
+          run: "issueTokens",
+          fn: tokens.issue,
+          args: ["$item"],
+          as: "tokens"
+        },
+        {
+          return: {
+            token: "$tokens.token",
+            refreshToken: "$tokens.refreshToken"
+          }
+        }
+      ]
+    };
+  }
+});
+export const logout = useCasePluginOf("logout", {
+  description: "Gives an empty token and refresh token: a route whose setCookie sends them removes the cookies. Tokens are not stored, so one already issued stays valid until it expires. Experimental.",
+  compile: (target, options) => {
+    checkOptions(target, options, []);
+    return {
+      ...metaOf(target, options, "Logout"),
+      blueprint: fields(() => ({})),
+      response: fields(() => ({
+        token: StringProperty,
+        refreshToken: StringProperty
+      })),
+      steps: [{ return: { token: "", refreshToken: "" } }]
+    };
+  }
+});