@pithy-sh/core 0.5.0 → 0.6.1

package/dist/image/storedImage.d.ts

@@ -0,0 +1,150 @@
+// 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 declare const STORED_IMAGE_TYPES: readonly ["image/png", "image/jpeg", "image/webp", "image/svg+xml"];
+/** 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 declare const INLINE_IMAGE_TYPES: readonly string[];
+/**
+ * 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 declare const MAX_STORED_IMAGE_CHARS: number;
+/**
+ * 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 declare const LONGEST_STORED_IMAGE_PREFIX: number;
+/**
+ * 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 declare const MAX_STORED_IMAGE_BYTES: number;
+/**
+ * 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 declare const StoredImage: z.ZodString;
+export type StoredImage = z.output<typeof StoredImage>;
+/** The type a stored image declares, or null when it is not a value this rule accepts. */
+export declare function typeOfStoredImage(stored: string): StoredImageType | 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 declare function storedImageSource(stored: string | null, path: string, version: Date | number): string | null;
+/** 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 declare function storedImageBytes(stored: string | null): StoredImageBytes | null;
+/**
+ * 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 declare const STORED_IMAGE_HEADERS: Readonly<Record<string, string>>;
+//# sourceMappingURL=storedImage.d.ts.map

package/dist/image/storedImage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"storedImage.d.ts","sourceRoot":"","sources":["../../src/image/storedImage.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAEH;;;;;;GAMG;AACH,eAAO,MAAM,kBAAkB,YAAI,WAAW,EAAE,YAAY,EAAE,YAAY,EAAE,eAAe,CAAU,CAAC;AAEtG,yCAAyC;AACzC,MAAM,MAAM,eAAe,GAAG,CAAC,OAAO,kBAAkB,CAAC,CAAC,MAAM,CAAC,CAAC;AAElE;;;;;;GAMG;AACH,eAAO,MAAM,kBAAkB,EAAE,SAAS,MAAM,EAAsB,CAAC;AAEvE;;;;;;GAMG;AACH,eAAO,MAAM,sBAAsB,QAAY,CAAC;AAEhD;;;;;GAKG;AACH,eAAO,MAAM,2BAA2B,QAA+E,CAAC;AAExH;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,sBAAsB,QAA6E,CAAC;AAOjH;;;;;;GAMG;AACH,eAAO,MAAM,WAAW,aAMrB,CAAC;AACJ,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,WAAW,CAAC,CAAC;AAOvD,0FAA0F;AAC1F,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,GAAG,eAAe,GAAG,IAAI,CAExE;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,IAAI,GAAG,MAAM,GAAG,MAAM,GAAG,IAAI,CAU5G;AAED,8DAA8D;AAC9D,MAAM,WAAW,gBAAgB;IAC/B,kGAAkG;IAClG,QAAQ,CAAC,IAAI,EAAE,eAAe,CAAC;IAC/B,wBAAwB;IACxB,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;CAC3B;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,GAAG,gBAAgB,GAAG,IAAI,CAe/E;AAED;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,oBAAoB,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAGjE,CAAC"}

package/dist/image/storedImage.js

@@ -0,0 +1,181 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+import { z } from "zod";
+//#region src/image/storedImage.ts
+/**
+* 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.
+*/
+const STORED_IMAGE_TYPES = [
+	"image/png",
+	"image/jpeg",
+	"image/webp",
+	"image/svg+xml"
+];
+/**
+* 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.
+*/
+const INLINE_IMAGE_TYPES = ["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.
+*/
+const MAX_STORED_IMAGE_CHARS = 32768;
+/**
+* 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.
+*/
+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.
+*/
+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.
+*/
+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`.");
+/** The `data:` prefix a stored image of `type` begins with. */
+function prefixOf(type) {
+	return `data:${type};base64,`;
+}
+/** The type a stored image declares, or null when it is not a value this rule accepts. */
+function typeOfStoredImage(stored) {
+	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.
+*/
+function storedImageSource(stored, path, version) {
+	if (stored === null) return null;
+	const type = typeOfStoredImage(stored);
+	if (type === null) return null;
+	if (INLINE_IMAGE_TYPES.includes(type)) return stored;
+	return `${path}?v=${version instanceof Date ? version.getTime() : version}`;
+}
+/**
+* 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.
+*/
+function storedImageBytes(stored) {
+	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;
+	try {
+		binary = atob(payload);
+	} catch {
+		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.
+*/
+const STORED_IMAGE_HEADERS = {
+	"cache-control": "private, max-age=31536000, immutable",
+	"x-content-type-options": "nosniff"
+};
+//#endregion
+export { INLINE_IMAGE_TYPES, LONGEST_STORED_IMAGE_PREFIX, MAX_STORED_IMAGE_BYTES, MAX_STORED_IMAGE_CHARS, STORED_IMAGE_HEADERS, STORED_IMAGE_TYPES, StoredImage, storedImageBytes, storedImageSource, typeOfStoredImage };

package/dist/logger/record.d.ts

@@ -798,6 +798,55 @@ export declare const LogRecord: z.ZodObject<{
         detail: z.ZodOptional<z.ZodString>;
         code: z.ZodLiteral<"controlplane/key_conflict">;
         status: z.ZodLiteral<409>;
+    }, z.core.$strip>, z.ZodObject<{
+        message: z.ZodString;
+        params: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>>;
+        action: z.ZodOptional<z.ZodString>;
+        detail: z.ZodOptional<z.ZodString>;
+        code: z.ZodLiteral<"organization/not_found">;
+        status: z.ZodLiteral<404>;
+    }, z.core.$strip>, z.ZodObject<{
+        message: z.ZodString;
+        params: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>>;
+        action: z.ZodOptional<z.ZodString>;
+        detail: z.ZodOptional<z.ZodString>;
+        code: z.ZodLiteral<"organization/forbidden">;
+        status: z.ZodLiteral<403>;
+    }, z.core.$strip>, z.ZodObject<{
+        message: z.ZodString;
+        params: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>>;
+        action: z.ZodOptional<z.ZodString>;
+        detail: z.ZodOptional<z.ZodString>;
+        code: z.ZodLiteral<"organization/invalid_role_catalog">;
+        status: z.ZodLiteral<400>;
+    }, z.core.$strip>, z.ZodObject<{
+        message: z.ZodString;
+        params: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>>;
+        action: z.ZodOptional<z.ZodString>;
+        detail: z.ZodOptional<z.ZodString>;
+        code: z.ZodLiteral<"organization/invitation_invalid">;
+        status: z.ZodLiteral<400>;
+    }, z.core.$strip>, z.ZodObject<{
+        message: z.ZodString;
+        params: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>>;
+        action: z.ZodOptional<z.ZodString>;
+        detail: z.ZodOptional<z.ZodString>;
+        code: z.ZodLiteral<"organization/last_administrator">;
+        status: z.ZodLiteral<409>;
+    }, z.core.$strip>, z.ZodObject<{
+        message: z.ZodString;
+        params: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>>;
+        action: z.ZodOptional<z.ZodString>;
+        detail: z.ZodOptional<z.ZodString>;
+        code: z.ZodLiteral<"organization/slug_taken">;
+        status: z.ZodLiteral<409>;
+    }, z.core.$strip>, z.ZodObject<{
+        message: z.ZodString;
+        params: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>>;
+        action: z.ZodOptional<z.ZodString>;
+        detail: z.ZodOptional<z.ZodString>;
+        code: z.ZodLiteral<"organization/nomination_invalid">;
+        status: z.ZodLiteral<400>;
     }, z.core.$strip>, z.ZodObject<{
         message: z.ZodString;
         params: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>>;

package/dist/logger/record.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"record.d.ts","sourceRoot":"","sources":["../../src/logger/record.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB;;;;;GAKG;AAEH,4GAA4G;AAC5G,eAAO,MAAM,QAAQ;;;;;EAE4F,CAAC;AAClH,MAAM,MAAM,QAAQ,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,QAAQ,CAAC,CAAC;AAEjD;;;GAGG;AACH,eAAO,MAAM,eAAe,EAAE,MAAM,CAAC,QAAQ,EAAE,MAAM,CAAgD,CAAC;AAEtG;;;;GAIG;AACH,eAAO,MAAM,SAAS,wCAEsF,CAAC;AAC7G,MAAM,MAAM,SAAS,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,SAAS,CAAC,CAAC;AAEnD;;;;;GAKG;AACH,eAAO,MAAM,SAAS;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAW+E,CAAC;AACtG,MAAM,MAAM,SAAS,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,SAAS,CAAC,CAAC;AAmBnD;;;GAGG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,SAAS,GAAG,MAAM,CAMzD"}
+{"version":3,"file":"record.d.ts","sourceRoot":"","sources":["../../src/logger/record.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB;;;;;GAKG;AAEH,4GAA4G;AAC5G,eAAO,MAAM,QAAQ;;;;;EAE4F,CAAC;AAClH,MAAM,MAAM,QAAQ,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,QAAQ,CAAC,CAAC;AAEjD;;;GAGG;AACH,eAAO,MAAM,eAAe,EAAE,MAAM,CAAC,QAAQ,EAAE,MAAM,CAAgD,CAAC;AAEtG;;;;GAIG;AACH,eAAO,MAAM,SAAS,wCAEsF,CAAC;AAC7G,MAAM,MAAM,SAAS,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,SAAS,CAAC,CAAC;AAEnD;;;;;GAKG;AACH,eAAO,MAAM,SAAS;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAW+E,CAAC;AACtG,MAAM,MAAM,SAAS,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,SAAS,CAAC,CAAC;AAmBnD;;;GAGG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,SAAS,GAAG,MAAM,CAMzD"}

package/dist/seed/devLogin.d.ts

@@ -9,10 +9,16 @@ import { z } from "zod";
  * 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. */
 export declare const SEED_ARTIFACT_DIR = "logs";
@@ -32,11 +38,13 @@ export declare const DEV_LOGIN_PATH = "logs/dev-login.json";
  * 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 declare 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 declare 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.
@@ -44,8 +52,7 @@ export declare const DEV_LOGIN_ROUTE = "/__pithy/dev-login";
 export declare const DevLogin: z.ZodObject<{
     email: z.ZodString;
     userId: z.ZodString;
-    cookieName: z.ZodString;
-    cookieValue: z.ZodString;
+    claim: z.ZodString;
     expiresAt: z.ZodCodec<z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodDate]>, z.ZodDate>;
 }, z.core.$strip>;
 export type DevLogin = z.output<typeof DevLogin>;

package/dist/seed/devLogin.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"devLogin.d.ts","sourceRoot":"","sources":["../../src/seed/devLogin.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB;;;;;;;;;;;;GAYG;AAEH,2GAA2G;AAC3G,eAAO,MAAM,iBAAiB,SAAS,CAAC;AAExC,gHAAgH;AAChH,eAAO,MAAM,cAAc,mBAAmB,CAAC;AAE/C,uGAAuG;AACvG,eAAO,MAAM,cAAc,wBAA2C,CAAC;AAEvE;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,eAAe,uBAAuB,CAAC;AAEpD;;;GAGG;AACH,eAAO,MAAM,QAAQ;;;;;;iBAc8F,CAAC;AACpH,MAAM,MAAM,QAAQ,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,QAAQ,CAAC,CAAC"}
+{"version":3,"file":"devLogin.d.ts","sourceRoot":"","sources":["../../src/seed/devLogin.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB;;;;;;;;;;;;;;;;;;GAkBG;AAEH,2GAA2G;AAC3G,eAAO,MAAM,iBAAiB,SAAS,CAAC;AAExC,gHAAgH;AAChH,eAAO,MAAM,cAAc,mBAAmB,CAAC;AAE/C,uGAAuG;AACvG,eAAO,MAAM,cAAc,wBAA2C,CAAC;AAEvE;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,eAAe,uBAAuB,CAAC;AAEpD,uGAAuG;AACvG,eAAO,MAAM,qBAAqB,MAAM,CAAC;AAEzC;;;GAGG;AACH,eAAO,MAAM,QAAQ;;;;;iBAWqF,CAAC;AAC3G,MAAM,MAAM,QAAQ,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,QAAQ,CAAC,CAAC"}

package/dist/seed/devLogin.js

@@ -11,10 +11,16 @@ import { z } from "zod";
 * 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. */
 const SEED_ARTIFACT_DIR = "logs";
@@ -34,21 +40,22 @@ 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.
 */
 const DEV_LOGIN_ROUTE = "/__pithy/dev-login";
+/** The query parameter {@link DEV_LOGIN_ROUTE} takes the claim in. Spelled once, read by both ends. */
+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.
 */
 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.string().describe("The signed, URI-encoded cookie value. A live credential for the local database — never logged, never committed, never in an error payload."),
-	expiresAt: JsonDate.describe("When the seeded session expires. 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`.");
+	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 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 claim stops being accepted. ISO-8601 text on disk; a `Date` in app code.")
+}).describe("A seeded dev login: the signed claim for one seeded user, written to `logs/dev-login.json`.");
 //#endregion
-export { DEV_LOGIN_FILE, DEV_LOGIN_PATH, DEV_LOGIN_ROUTE, DevLogin, SEED_ARTIFACT_DIR };
+export { DEV_LOGIN_CLAIM_PARAM, DEV_LOGIN_FILE, DEV_LOGIN_PATH, DEV_LOGIN_ROUTE, DevLogin, SEED_ARTIFACT_DIR };

package/dist/version.generated.d.ts

@@ -3,5 +3,5 @@
 /** This package's npm name — the join key against a release feed. */
 export declare const PACKAGE_NAME = "@pithy-sh/core";
 /** This package's version, stamped from its own package.json at generation time. */
-export declare const PACKAGE_VERSION = "0.5.0";
+export declare const PACKAGE_VERSION = "0.6.1";
 //# sourceMappingURL=version.generated.d.ts.map

package/dist/version.generated.js

@@ -4,6 +4,6 @@
 /** This package's npm name — the join key against a release feed. */
 const PACKAGE_NAME = "@pithy-sh/core";
 /** This package's version, stamped from its own package.json at generation time. */
-const PACKAGE_VERSION = "0.5.0";
+const PACKAGE_VERSION = "0.6.1";
 //#endregion
 export { PACKAGE_NAME, PACKAGE_VERSION };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pithy-sh/core",
-  "version": "0.5.0",
+  "version": "0.6.1",
   "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)