@pithy-sh/core 0.5.0 → 0.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pithy-sh/core",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "license": "MIT",
   "repository": {
     "type": "git",

package/src/capability/manifest.ts

@@ -497,6 +497,13 @@ export const CONFIG_SEAMS = {
     describe:
       "Which organization this caller is acting for. Scaffolded unimplemented — this Worker refuses to boot until src/billing/subject.ts answers it.",
   },
+  organizationRoles: {
+    binding: "roles",
+    module: "src/organization/roles.ts",
+    specifier: "./src/organization/roles",
+    describe:
+      "Who may do what here. Scaffolded with a starter matrix — the role names and the powers they hold are this product's, and only this project's code can state them.",
+  },
 } as const satisfies Record<string, ConfigSeamSpec>;
 
 /** Which scaffolded seam a choice needs, by key. */
@@ -681,6 +688,12 @@ export const CapabilityManifest = z
       .describe(
         "Every secret from this capability's registry that declares how it comes to exist and how it is replaced. The route `devSecrets` proved: a client reads it without executing the package, so `pithy doctor` says *not set — run this* or *not set — get it here*, and no client keeps its own table of names. A secret declaring neither axis is absent, which reads as *nothing is known*, not as *nothing can help*.",
       ),
+    seams: z
+      .array(ConfigSeam)
+      .default([])
+      .describe(
+        "Seams this capability needs **always**, rather than under one choice of one option. `pithy add` writes each module into the Worker, imports it, and passes it to the factory beside the config values — the same machinery `choicesNeedingSeam` drives, without the condition. `organization`'s role catalog is the one: a tenancy capability has no answer to *who may do what* that is not the adopter's, so there is no configuration under which the module is unnecessary and nothing to make it conditional on. Named from `CONFIG_SEAMS`, so nothing a manifest states is written into generated source unquoted (#183).",
+      ),
     scaffold: z.array(z.string()).default([]).describe("Human-readable scaffold steps the CLI performs or explains."),
     configOptions: z
       .array(ConfigOption)

package/src/error/payload.ts

@@ -1275,6 +1275,90 @@ const ControlPlaneKeyConflictPublic = z
   })
   .describe("A key operation conflicts with the connection's current state (409).");
 
+// --- @pithy-sh/organization: tenancy, roles, invitations and ownership codes ---
+
+const OrganizationNotFoundPublic = z
+  .object({
+    code: z
+      .literal("organization/not_found")
+      .describe(
+        "The named organization does not exist, **or** the caller is not a member of it. One code for two facts, deliberately: a distinguishable refusal is an existence oracle, and iterating it produces the customer list. Which of the two it was survives in `detail`, which the HTTP codec strips and the log keeps.",
+      ),
+    status: z.literal(404).describe("Not Found."),
+    ...publicFields,
+  })
+  .describe("No such organization, or none this caller belongs to — the same answer for both (404).");
+
+const OrganizationForbiddenPublic = z
+  .object({
+    code: z
+      .literal("organization/forbidden")
+      .describe(
+        "The caller is a proved member whose role does not hold the power the route asked for. A 403 rather than the 404 above, and the difference is earned: by the time this is raised they already know the organization exists, because they belong to it.",
+      ),
+    status: z.literal(403).describe("Forbidden — a member, but not one who may do this."),
+    ...publicFields,
+  })
+  .describe("A member's role does not hold the required power (403).");
+
+const OrganizationInvalidRoleCatalogPublic = z
+  .object({
+    code: z
+      .literal("organization/invalid_role_catalog")
+      .describe(
+        "A role catalog failed validation. Raised by `defineRoles` at author time — a redeclared kit power, an `administrativePower` nobody holds, a kit power no role holds, or a claimed nesting that does not hold — so a mistake fails where the catalog is written rather than the first time somebody is refused by it.",
+      ),
+    status: z.literal(400).describe("Bad Request — the catalog declaration is malformed."),
+    ...publicFields,
+  })
+  .describe("A role catalog declaration is invalid (400).");
+
+const OrganizationInvitationInvalidPublic = z
+  .object({
+    code: z
+      .literal("organization/invitation_invalid")
+      .describe(
+        "An invitation cannot be redeemed: no such token, already used, withdrawn, past its date, or presented by a session whose own address is not the one invited. One code for all five, because telling somebody which it was tells whoever forwarded the link the same thing.",
+      ),
+    status: z.literal(400).describe("Bad Request — the offer is not redeemable by this caller."),
+    ...publicFields,
+  })
+  .describe("An invitation is not redeemable (400).");
+
+const OrganizationLastAdministratorPublic = z
+  .object({
+    code: z
+      .literal("organization/last_administrator")
+      .describe(
+        "The write would leave the account with nobody holding `administrativePower`. Counted over the power rather than over a role spelled `admin`, so a catalog where an owner also administers does not become unadministrable when its one admin leaves.",
+      ),
+    status: z.literal(409).describe("Conflict — an account nobody can administer is not a state to arrive at."),
+    ...publicFields,
+  })
+  .describe("The last administrator cannot be demoted, removed, or leave (409).");
+
+const OrganizationSlugTakenPublic = z
+  .object({
+    code: z
+      .literal("organization/slug_taken")
+      .describe("Another organization already holds that slug. A slug addresses one account, so it is unique."),
+    status: z.literal(409).describe("Conflict."),
+    ...publicFields,
+  })
+  .describe("That slug is already in use (409).");
+
+const OrganizationNominationInvalidPublic = z
+  .object({
+    code: z
+      .literal("organization/nomination_invalid")
+      .describe(
+        "An ownership offer cannot be accepted: none stands, it was replaced, it has expired, or it was made to somebody else. Ownership moves only by offer and acceptance, so a refusal here is the transfer declining to happen rather than a permission being short.",
+      ),
+    status: z.literal(400).describe("Bad Request — no offer this caller may accept."),
+    ...publicFields,
+  })
+  .describe("No standing ownership offer this caller may accept (400).");
+
 // --- @pithy-sh/support: inbound inbox, taxonomy, and classification codes ---
 
 const SupportNotFoundPublic = z
@@ -1577,6 +1661,13 @@ export const KitPublicErrorPayload = z
     ControlPlaneInsufficientScopePublic,
     ControlPlaneKeyNotFoundPublic,
     ControlPlaneKeyConflictPublic,
+    OrganizationNotFoundPublic,
+    OrganizationForbiddenPublic,
+    OrganizationInvalidRoleCatalogPublic,
+    OrganizationInvitationInvalidPublic,
+    OrganizationLastAdministratorPublic,
+    OrganizationSlugTakenPublic,
+    OrganizationNominationInvalidPublic,
     SupportNotFoundPublic,
     SupportInvalidCategoryPublic,
     SupportUnparseableMessagePublic,
@@ -1917,6 +2008,28 @@ const TestersNotConfigured = TestersNotConfiguredPublic.extend(internalFields).d
   TestersNotConfiguredPublic.description ?? "",
 );
 
+const OrganizationNotFound = OrganizationNotFoundPublic.extend(internalFields).describe(
+  OrganizationNotFoundPublic.description ?? "",
+);
+const OrganizationForbidden = OrganizationForbiddenPublic.extend(internalFields).describe(
+  OrganizationForbiddenPublic.description ?? "",
+);
+const OrganizationInvalidRoleCatalog = OrganizationInvalidRoleCatalogPublic.extend(internalFields).describe(
+  OrganizationInvalidRoleCatalogPublic.description ?? "",
+);
+const OrganizationInvitationInvalid = OrganizationInvitationInvalidPublic.extend(internalFields).describe(
+  OrganizationInvitationInvalidPublic.description ?? "",
+);
+const OrganizationLastAdministrator = OrganizationLastAdministratorPublic.extend(internalFields).describe(
+  OrganizationLastAdministratorPublic.description ?? "",
+);
+const OrganizationSlugTaken = OrganizationSlugTakenPublic.extend(internalFields).describe(
+  OrganizationSlugTakenPublic.description ?? "",
+);
+const OrganizationNominationInvalid = OrganizationNominationInvalidPublic.extend(internalFields).describe(
+  OrganizationNominationInvalidPublic.description ?? "",
+);
+
 const SupportNotFound = SupportNotFoundPublic.extend(internalFields).describe(SupportNotFoundPublic.description ?? "");
 const SupportInvalidCategory = SupportInvalidCategoryPublic.extend(internalFields).describe(
   SupportInvalidCategoryPublic.description ?? "",
@@ -2046,6 +2159,13 @@ export const KitErrorPayload = z
     ControlPlaneInsufficientScope,
     ControlPlaneKeyNotFound,
     ControlPlaneKeyConflict,
+    OrganizationNotFound,
+    OrganizationForbidden,
+    OrganizationInvalidRoleCatalog,
+    OrganizationInvitationInvalid,
+    OrganizationLastAdministrator,
+    OrganizationSlugTaken,
+    OrganizationNominationInvalid,
     SupportNotFound,
     SupportInvalidCategory,
     SupportUnparseableMessage,

package/src/image/storedImage.ts

@@ -0,0 +1,209 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { z } from "zod";
+
+/**
+ * What may be stored as an image, and how it is served — stated once, for every capability that holds
+ * a small picture in a column.
+ *
+ * Two capabilities hold one: `@pithy-sh/auth` keeps a person's face, `@pithy-sh/organization` keeps an
+ * account's mark. They are the same object at different scales, and **two answers to *what may be
+ * stored as an image* is one of them being wrong.** So the allowlist, the ceiling, the derived byte
+ * figure and the serving split live here and are imported, exactly as `normalizeAddress` moved here in
+ * `#280`.
+ *
+ * ## Stored, not linked
+ *
+ * A remote URL means the page fetching an attacker-chosen host from a screen listing people, leaking
+ * the viewer's IP and referrer before they had done anything, and it needs a CSP hole to render at all.
+ * A bounded `data:` URL in a column has no third party in it.
+ *
+ * ## Rendered through `<img>`, never inlined
+ *
+ * A browser disables scripting inside an `<img>` by specification, and that is the entire basis for
+ * accepting SVG here at all. Nothing in the kit writes one of these values into a document.
+ *
+ * ## Rasters get a URL, vectors never do — and that is the security answer, not a mitigation
+ *
+ * A `data:` URL has one property it cannot have: **it cannot be cached.** It is inline in the response
+ * body, so a roster of twenty faces re-sends twenty images on every read, forever. Serving from the
+ * app's own origin fixes that and costs one real hazard — **an SVG fetched by *navigation* runs script
+ * in the origin that served it.** An `<img src>` is inert; a URL is navigable.
+ *
+ * So a vector never gets a URL. {@link storedImageBytes} answers null for one, the serving route 404s
+ * on null, and there is no arrangement of ids and versions that makes the origin return an SVG. The
+ * class of attack is removed rather than managed with headers, and there is no header anybody has to
+ * keep right.
+ */
+
+/**
+ * The image types a stored picture may be.
+ *
+ * Three rasters and one vector. The vector is here because `<img>` renders it inertly and a mark drawn
+ * as one is a few hundred bytes; every rule below that treats it differently is treating *navigability*
+ * differently, not the format.
+ */
+export const STORED_IMAGE_TYPES = ["image/png", "image/jpeg", "image/webp", "image/svg+xml"] as const;
+
+/** One of {@link STORED_IMAGE_TYPES}. */
+export type StoredImageType = (typeof STORED_IMAGE_TYPES)[number];
+
+/**
+ * The types that stay inline whatever else happens.
+ *
+ * One entry, and the module note argues it at length. Written as a list rather than as a comparison so
+ * that a second scriptable format added to {@link STORED_IMAGE_TYPES} one day is added here too, next
+ * to the reason.
+ */
+export const INLINE_IMAGE_TYPES: readonly string[] = ["image/svg+xml"];
+
+/**
+ * The ceiling on a stored image, in characters of `data:` URL.
+ *
+ * 32KB of base64, which is about 24KB of image. A face drawn at 34px does not need more, and the
+ * ceiling is what stops one row making every read expensive: the record, the account menu and the
+ * chooser all carry it.
+ */
+export const MAX_STORED_IMAGE_CHARS = 32 * 1024;
+
+/**
+ * The longest `data:<type>;base64,` a stored image can begin with, in characters.
+ *
+ * Derived from the allowlist rather than written down, so a longer type name added above cannot leave a
+ * ceiling below it stale. `image/svg+xml` is the long one today, at 26 characters.
+ */
+export const LONGEST_STORED_IMAGE_PREFIX = Math.max(...STORED_IMAGE_TYPES.map((type) => `data:${type};base64,`.length));
+
+/**
+ * The largest file a browser may encode into that ceiling, in bytes of image.
+ *
+ * **Not `MAX_STORED_IMAGE_CHARS * 3 / 4`, and the difference is a bug that shipped once.** That is the
+ * base64 inverse, and it silently assumes the stored string is base64 and nothing else. It is not: it
+ * is `data:<type>;base64,` and *then* the base64. A file at the plain inverse encodes to 22–26
+ * characters more than the column will take, so it passes a picker's own check and is refused by Zod —
+ * the person gets a validator's sentence where the product had written them one of its own.
+ *
+ * Base64 is four characters per three bytes and rounds up to a whole group, so the arithmetic runs
+ * backwards from the characters left after the prefix: `floor((chars - prefix) / 4)` groups, three
+ * bytes each. Derived from the *longest* prefix, because one ceiling has to hold for every type a
+ * picker offers and the tightest constraint is the one that binds.
+ *
+ * **This is the figure a client-side picker checks a file against before encoding it.** The column
+ * enforces {@link MAX_STORED_IMAGE_CHARS} on the whole string, which is the bound that matters; this is
+ * the same fact stated as bytes of image, so a picker and a column cannot disagree.
+ */
+export const MAX_STORED_IMAGE_BYTES = 3 * Math.floor((MAX_STORED_IMAGE_CHARS - LONGEST_STORED_IMAGE_PREFIX) / 4);
+
+/** `data:<type>;base64,<payload>` and nothing else — no bare URL, no `data:text/html`, no charset games. */
+const STORED_IMAGE_PATTERN = new RegExp(
+  `^data:(?:${STORED_IMAGE_TYPES.join("|").replace(/\+/g, "\\+")});base64,[A-Za-z0-9+/]+=*$`,
+);
+
+/**
+ * A stored image, validated at the column and therefore at every boundary that decodes a row.
+ *
+ * **The pattern is an allowlist of types, not a check that the string starts with `data:`.**
+ * `data:text/html` is a `data:` URL too, and the difference between the two is the whole of what makes
+ * this column safe to render. Anchored at both ends, so nothing follows the payload.
+ */
+export const StoredImage = z
+  .string()
+  .max(MAX_STORED_IMAGE_CHARS)
+  .regex(STORED_IMAGE_PATTERN)
+  .describe(
+    "An image held as a base64 `data:` URL of an allowed type, bounded to 32KB. Stored rather than linked, and rendered only through `<img>` — see `@pithy-sh/core/src/image/storedImage`.",
+  );
+export type StoredImage = z.output<typeof StoredImage>;
+
+/** The `data:` prefix a stored image of `type` begins with. */
+function prefixOf(type: string): string {
+  return `data:${type};base64,`;
+}
+
+/** The type a stored image declares, or null when it is not a value this rule accepts. */
+export function typeOfStoredImage(stored: string): StoredImageType | null {
+  return STORED_IMAGE_TYPES.find((type) => stored.startsWith(prefixOf(type))) ?? null;
+}
+
+/**
+ * What a screen should draw this image from.
+ *
+ * A URL for a raster, the stored value itself for a vector, and null for nothing. The caller renders
+ * whichever it gets through the same `<img src>`, so no screen has to know which it was handed.
+ *
+ * `path` is the route the owning capability serves bytes from, already carrying whatever identifies the
+ * subject — this function appends only the version, because the version is the half that has to be
+ * right for `immutable` to be honest.
+ *
+ * The version is the owning row's `updatedAt`: the URL changes whenever the image can have changed, so
+ * the response may be `immutable` and a browser never revalidates. It over-invalidates slightly — a
+ * rename busts a picture that did not change — which is one wasted fetch on a rare action, against a
+ * hash column and a migration to carry it.
+ */
+export function storedImageSource(stored: string | null, path: string, version: Date | number): string | null {
+  if (stored === null) return null;
+  const type = typeOfStoredImage(stored);
+  // Not a value this build recognizes. Answered as nothing rather than served: a face falls back to
+  // initials, which is a real answer, and a value the allowlist does not match is one the column should
+  // never have held.
+  if (type === null) return null;
+  if (INLINE_IMAGE_TYPES.includes(type)) return stored;
+  const at = version instanceof Date ? version.getTime() : version;
+  return `${path}?v=${at}`;
+}
+
+/** A stored image decoded into what a response body needs. */
+export interface StoredImageBytes {
+  /** The `Content-Type` to serve it as. Always one of {@link STORED_IMAGE_TYPES}, never sniffed. */
+  readonly type: StoredImageType;
+  /** The image itself. */
+  readonly body: Uint8Array;
+}
+
+/**
+ * Decode a stored image for serving, or null when it must not be served.
+ *
+ * **Null for a vector, and that is the gate rather than a caution.** The route asks this and answers
+ * 404 when it gets null, so there is no arrangement of ids and versions that makes the origin return an
+ * SVG. The module note gives the reason.
+ *
+ * Null too for anything the allowlist does not match, which the column should have refused on the way
+ * in — this is the second place that is true, and a value that reached the column past a bug does not
+ * get served out of it.
+ */
+export function storedImageBytes(stored: string | null): StoredImageBytes | null {
+  if (stored === null) return null;
+  const type = typeOfStoredImage(stored);
+  if (type === null || INLINE_IMAGE_TYPES.includes(type)) return null;
+  const payload = stored.slice(prefixOf(type).length);
+  let binary: string;
+  try {
+    binary = atob(payload);
+  } catch {
+    // A column value that is not decodable base64. Nothing to serve, and nothing to say about it here.
+    return null;
+  }
+  const body = new Uint8Array(binary.length);
+  for (let at = 0; at < binary.length; at += 1) body[at] = binary.charCodeAt(at);
+  return { type, body };
+}
+
+/**
+ * The headers a served image carries.
+ *
+ * **`immutable`, which is only honest because the URL carries a version.** {@link storedImageSource}
+ * puts the owning row's `updatedAt` in the query, so a changed image is a different URL and a browser
+ * that never revalidates can never show a stale one.
+ *
+ * **`private`, because the fetch is authorized against a session.** A shared cache holding this would
+ * be one person's face served to whoever asked next.
+ *
+ * **`nosniff`, because the type is the allowlist's and must not be re-guessed.** Content sniffing is
+ * how a file served as an image gets treated as something else, and the whole safety of this route is
+ * that the type is one of three rasters.
+ */
+export const STORED_IMAGE_HEADERS: Readonly<Record<string, string>> = {
+  "cache-control": "private, max-age=31536000, immutable",
+  "x-content-type-options": "nosniff",
+};

package/src/seed/devLogin.ts

@@ -12,10 +12,16 @@ import { JsonDate } from "../data/codecs";
  * the seam they already share, so the shape is stated once instead of being duplicated (and drifting) at
  * both ends.
  *
- * **The file holds a live credential.** A signed session cookie for a local database is a way in for
- * anyone who can read it, which is why it is written under `logs/` — gitignored by the starter template,
- * so it can never be committed — and why nothing here is ever put in a `PithyError` (the payload reaches
- * logs verbatim).
+ * **The file holds a live credential.** A signed claim for a local database is a way in for anyone who
+ * can read it, which is why it is written under `logs/` — gitignored by the starter template, so it can
+ * never be committed — and why nothing here is ever put in a `PithyError` (the payload reaches logs
+ * verbatim).
+ *
+ * **It used to hold a session cookie, and now it holds a claim — `#572`.** The difference is what
+ * survives: a cookie names a row in `pithy_auth_sessions`, so signing out of the app revoked it and the
+ * dev login 404'd until somebody reseeded. A claim names a *user*, signed with the session secret, and
+ * the route exchanges it for a fresh session on every open. Sign-out then revokes the session it should
+ * revoke and leaves the way back in alone.
  */
 
 /** The directory seed artifacts are written to, relative to the project root. Gitignored, so transient. */
@@ -39,29 +45,29 @@ export const DEV_LOGIN_PATH = `${SEED_ARTIFACT_DIR}/${DEV_LOGIN_FILE}`;
  * anything the kit serves that is not part of a capability's public surface lives under this prefix, so
  * a route added here can never collide with an application path someone already shipped.
  *
- * Registered **only** in a `dev` composition, and never under CI. It mints an authenticated session with
- * no credential presented, which is the whole risk of the feature and the reason its gates live at
- * registration rather than inside the handler.
+ * Registered **only** in a `dev` composition, and never under CI. It mints an authenticated session for
+ * whoever presents a claim this project's own secret signed, which is the whole risk of the feature and
+ * the reason its gates live at registration rather than inside the handler.
  */
 export const DEV_LOGIN_ROUTE = "/__pithy/dev-login";
 
+/** The query parameter {@link DEV_LOGIN_ROUTE} takes the claim in. Spelled once, read by both ends. */
+export const DEV_LOGIN_CLAIM_PARAM = "t";
+
 /**
  * A seeded dev login — everything a browser needs to be signed in as a seeded user, and nothing else.
  * `z.input` is the JSON on disk (dates as ISO-8601 strings); `z.output` is the app shape.
  */
 export const DevLogin = z
   .object({
-    email: z.string().describe("The seeded user this cookie signs in as. Shown on the `pithy dev` ready banner."),
-    userId: z.string().describe("The seeded user's id, so a tool can correlate the cookie with the seeded rows."),
-    cookieName: z
-      .string()
-      .describe("The cookie name the auth capability's session is read from, e.g. `better-auth.session_token`."),
-    cookieValue: z
+    email: z.string().describe("The seeded user this claim signs in as. Shown on the `pithy dev` ready banner."),
+    userId: z.string().describe("The seeded user's id, so a tool can correlate the login with the seeded rows."),
+    claim: z
       .string()
       .describe(
-        "The signed, URI-encoded cookie value. A live credential for the local database — never logged, never committed, never in an error payload.",
+        "The signed, URI-encoded claim naming the user to sign in as. A live credential for the local database — never logged, never committed, never in an error payload. **Not a session:** it names a user and the route mints a session against it, so revoking a session leaves it working.",
       ),
-    expiresAt: JsonDate.describe("When the seeded session expires. ISO-8601 text on disk; a `Date` in app code."),
+    expiresAt: JsonDate.describe("When the claim stops being accepted. ISO-8601 text on disk; a `Date` in app code."),
   })
-  .describe("A seeded dev login: the signed session cookie for one seeded user, written to `logs/dev-login.json`.");
+  .describe("A seeded dev login: the signed claim for one seeded user, written to `logs/dev-login.json`.");
 export type DevLogin = z.output<typeof DevLogin>;

package/src/version.generated.ts

@@ -13,4 +13,4 @@
 export const PACKAGE_NAME = "@pithy-sh/core";
 
 /** This package's version, stamped from its own package.json at generation time. */
-export const PACKAGE_VERSION = "0.5.0";
+export const PACKAGE_VERSION = "0.6.0";