@brydio/manifest 0.1.0-alpha.37 → 0.1.0-alpha.39

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@brydio/manifest",
-  "version": "0.1.0-alpha.37",
+  "version": "0.1.0-alpha.39",
   "description": "The shape of a Brydio app's manifest, its collections' schemas, and the checks that say what is wrong with one.",
   "type": "module",
   "license": "MIT",
@@ -10,7 +10,7 @@
     "url": "https://github.com/nakel-ola/brydio-sdk",
     "directory": "packages/manifest"
   },
-  "gitHead": "c0364642e34a602b75477af366aa61582e5598f7",
+  "gitHead": "4b20d567d9361683e104ec609d231111bd93bcbf",
   "exports": {
     ".": {
       "types": "./src/index.d.ts",

package/src/field-types.d.ts

@@ -40,6 +40,12 @@ export interface FieldType {
      * row's table. Set by the host only, never parsed from a manifest.
      */
     plain?: boolean;
+    /**
+     * The most entries a `string[]` holds, when not `FIELD_LIMITS.listEntries`:
+     * a collection's readers or editors field takes `READERS_LIMIT` (P16,
+     * DW06). Set by the host only, never parsed from a manifest.
+     */
+    maxEntries?: number;
 }
 /**
  * The bounds a schema and a record are held to (A3-F01-S03).

package/src/field-types.js

@@ -259,7 +259,7 @@ export function valueSchema(type) {
         case 'boolean':
             return z.boolean();
         case 'string[]':
-            return z.array(z.string().max(FIELD_LIMITS.stringChars)).max(FIELD_LIMITS.listEntries);
+            return z.array(z.string().max(FIELD_LIMITS.stringChars)).max(type.maxEntries ?? FIELD_LIMITS.listEntries);
         case 'canvas':
             return z.object({ elements: z.number().int().min(0), text: z.string().max(CANVAS_SUMMARY_CHARS) }).strict();
     }
@@ -294,8 +294,8 @@ export function valueProblem(field, type, value) {
         case 'boolean':
             return `${field} must be true or false.`;
         case 'string[]':
-            return Array.isArray(value) && value.length > FIELD_LIMITS.listEntries
-                ? `${field} may hold at most ${FIELD_LIMITS.listEntries} entries.`
+            return Array.isArray(value) && value.length > (type.maxEntries ?? FIELD_LIMITS.listEntries)
+                ? `${field} may hold at most ${type.maxEntries ?? FIELD_LIMITS.listEntries} entries.`
                 : `${field} must be a list of short texts, each at most ${FIELD_LIMITS.stringChars.toLocaleString('en-GB')} characters.`;
         case 'canvas':
             return `${field} is a drawing: it is changed on its board, never written.`;

package/src/index.d.ts

@@ -11,6 +11,7 @@ export { appManifestSchema, appToolPrefix, collectionOf, crossAppTool, collectio
 export { OPEN_LIMITS, OPEN_TYPES, choicesProblem, definitionOf, definitionTypeProblem, describeField, fieldTypeOf, hasChoices, isPlainOpenType, keyFromName, keyProblem, missingRequired, moveValue, openSchemaProblems, openSpec, openValueProblem, type Moved, type OpenField, type OpenFieldChange, type OpenFieldValue, type OpenProblem, type OpenProblemCode, type OpenSchemaFlag, type OpenType, } from './open-schema.js';
 export { CONFIRM_LIMITS, confirmEmailProblems, confirmEmailSpec, type ConfirmEmailDeclared, type ConfirmEmailSpec, type ConfirmProblemCode, } from './confirm-email.js';
 export { ANONYMOUS_LIMITS, ANONYMOUS_WRITER, anonymousProblems, anonymousSpec, type AnonymousDeclared, type AnonymousProblemCode, type AnonymousSpec, } from './anonymous.js';
+export { editorsOf, editorsProblems, READERS_LIMIT, readersOf, readersProblems, type EditorsProblemCode, type ReadersProblemCode } from './readers.js';
 export { DOCUMENT_LIMITS } from './document-limits.js';
 export { HOST_CAPABILITIES, KNOWN_HOST_GRANTS, isHostCapability, unknownHostGrant } from './grants.js';
 export { diffSchemas, migrationProblems, migrationSchema, migrationStepSchema, migrationsSchema, publishedMigrationProblems, schemaOf, type Migration, type MigrationCode, type MigrationProblem, type MigrationStep, type SchemaChange, } from './migrations.js';

package/src/index.js

@@ -11,6 +11,7 @@ export { appManifestSchema, appToolPrefix, collectionOf, crossAppTool, collectio
 export { OPEN_LIMITS, OPEN_TYPES, choicesProblem, definitionOf, definitionTypeProblem, describeField, fieldTypeOf, hasChoices, isPlainOpenType, keyFromName, keyProblem, missingRequired, moveValue, openSchemaProblems, openSpec, openValueProblem, } from "./open-schema.js";
 export { CONFIRM_LIMITS, confirmEmailProblems, confirmEmailSpec, } from "./confirm-email.js";
 export { ANONYMOUS_LIMITS, ANONYMOUS_WRITER, anonymousProblems, anonymousSpec, } from "./anonymous.js";
+export { editorsOf, editorsProblems, READERS_LIMIT, readersOf, readersProblems } from "./readers.js";
 export { DOCUMENT_LIMITS } from "./document-limits.js";
 export { HOST_CAPABILITIES, KNOWN_HOST_GRANTS, isHostCapability, unknownHostGrant } from "./grants.js";
 export { diffSchemas, migrationProblems, migrationSchema, migrationStepSchema, migrationsSchema, publishedMigrationProblems, schemaOf, } from "./migrations.js";

package/src/readers.d.ts

@@ -0,0 +1,54 @@
+import { z } from 'zod';
+/**
+ * Record readers (P16): a record only the people it
+ * names may read.
+ *
+ * An app names one of the collection's own `string[]` fields, which holds
+ * user ids. When a record's list is empty, everyone who can read the
+ * instance reads it, as before; when it names anyone, nobody else finds it —
+ * not on a screen, not through a tool, not through the assistant, not on the
+ * co-edit socket. There is no admin past it: an app that wants its admins
+ * in puts them in the list. Brydio keeps the list in plain beside the record
+ * (`app_document.readers`), so every read can be narrowed before anything
+ * is decrypted. Mirrors Brydio's `apps/api/src/apps/manifest/readers.ts`;
+ * the two change together.
+ */
+export declare const readersSchema: z.ZodString;
+export type ReadersProblemCode = 'data_readers_field' | 'data_readers_anonymous';
+/** The most people one record's list may name. */
+export declare const READERS_LIMIT = 1000;
+export declare function readersProblems(collection: string, declared: {
+    schema: Record<string, unknown>;
+    readers?: string;
+    anonymous?: unknown;
+}): {
+    code: ReadersProblemCode;
+    collection: string;
+    field?: string;
+    message: string;
+}[];
+/** The plain list a record is kept with: its readers, or null for everyone who can read the instance. */
+export declare function readersOf(field: string | undefined, body: Record<string, unknown>): string[] | null;
+/**
+ * Record editors (DW06): a record only the people it names may change. The
+ * same shape as readers: one of the collection's own `string[]` fields of
+ * user ids, kept in plain beside the record (`app_document.editors`). Empty,
+ * and anyone who may write the instance may change it; naming anyone, and
+ * only they may — through a tool, a handler, the assistant or the co-edit
+ * socket, where anyone else's connection is read-only. Everyone who may read
+ * the record still reads it.
+ */
+export declare const editorsSchema: z.ZodString;
+export type EditorsProblemCode = 'data_editors_field' | 'data_editors_anonymous';
+export declare function editorsProblems(collection: string, declared: {
+    schema: Record<string, unknown>;
+    editors?: string;
+    anonymous?: unknown;
+}): {
+    code: EditorsProblemCode;
+    collection: string;
+    field?: string;
+    message: string;
+}[];
+/** The plain list a record is kept with: its editors, or null for anyone who may write the instance. */
+export declare const editorsOf: typeof readersOf;

package/src/readers.js

@@ -0,0 +1,96 @@
+import { z } from 'zod';
+import { FIELD_LIMITS, parseFieldType } from "./field-types.js";
+/**
+ * Record readers (P16): a record only the people it
+ * names may read.
+ *
+ * An app names one of the collection's own `string[]` fields, which holds
+ * user ids. When a record's list is empty, everyone who can read the
+ * instance reads it, as before; when it names anyone, nobody else finds it —
+ * not on a screen, not through a tool, not through the assistant, not on the
+ * co-edit socket. There is no admin past it: an app that wants its admins
+ * in puts them in the list. Brydio keeps the list in plain beside the record
+ * (`app_document.readers`), so every read can be narrowed before anything
+ * is decrypted. Mirrors Brydio's `apps/api/src/apps/manifest/readers.ts`;
+ * the two change together.
+ */
+export const readersSchema = z.string().min(1).max(FIELD_LIMITS.nameChars);
+/** The most people one record's list may name. */
+export const READERS_LIMIT = 1_000;
+export function readersProblems(collection, declared) {
+    if (!declared.readers)
+        return [];
+    const problems = [];
+    const raw = declared.schema[declared.readers];
+    let listed = false;
+    try {
+        listed = raw !== undefined && parseFieldType(raw).kind === 'string[]';
+    }
+    catch {
+        // Refused as a field type already.
+    }
+    if (!listed) {
+        problems.push({
+            code: 'data_readers_field',
+            collection,
+            field: declared.readers,
+            message: `"${collection}" names "${declared.readers}" as its readers, which must be one of its own string[] fields holding user ids.`,
+        });
+    }
+    // An anonymous answer names nobody; a list of who may read it would.
+    if (declared.anonymous) {
+        problems.push({
+            code: 'data_readers_anonymous',
+            collection,
+            message: `"${collection}" can't be anonymous and name its readers.`,
+        });
+    }
+    return problems;
+}
+/** The plain list a record is kept with: its readers, or null for everyone who can read the instance. */
+export function readersOf(field, body) {
+    if (!field)
+        return null;
+    const value = body[field];
+    if (!Array.isArray(value))
+        return null;
+    const ids = [...new Set(value.filter((one) => typeof one === 'string' && one.length > 0))];
+    return ids.length ? ids.sort() : null;
+}
+/**
+ * Record editors (DW06): a record only the people it names may change. The
+ * same shape as readers: one of the collection's own `string[]` fields of
+ * user ids, kept in plain beside the record (`app_document.editors`). Empty,
+ * and anyone who may write the instance may change it; naming anyone, and
+ * only they may — through a tool, a handler, the assistant or the co-edit
+ * socket, where anyone else's connection is read-only. Everyone who may read
+ * the record still reads it.
+ */
+export const editorsSchema = readersSchema;
+export function editorsProblems(collection, declared) {
+    if (!declared.editors)
+        return [];
+    const problems = [];
+    const raw = declared.schema[declared.editors];
+    let listed = false;
+    try {
+        listed = raw !== undefined && parseFieldType(raw).kind === 'string[]';
+    }
+    catch {
+        // Refused as a field type already.
+    }
+    if (!listed) {
+        problems.push({
+            code: 'data_editors_field',
+            collection,
+            field: declared.editors,
+            message: `"${collection}" names "${declared.editors}" as its editors, which must be one of its own string[] fields holding user ids.`,
+        });
+    }
+    if (declared.anonymous) {
+        problems.push({ code: 'data_editors_anonymous', collection, message: `"${collection}" can't be anonymous and name its editors.` });
+    }
+    return problems;
+}
+/** The plain list a record is kept with: its editors, or null for anyone who may write the instance. */
+export const editorsOf = readersOf;

package/src/schema.d.ts

@@ -3,6 +3,7 @@ import { FieldTypeInvalid, type FieldType } from './field-types.js';
 import { type OpenProblemCode } from './open-schema.js';
 import { type ConfirmProblemCode } from './confirm-email.js';
 import { type AnonymousProblemCode, type AnonymousSpec } from './anonymous.js';
+import { type EditorsProblemCode, type ReadersProblemCode } from './readers.js';
 export { COLOUR_TOKENS, FIELD_LIMITS, parseFieldType, RESERVED_FIELDS, structuredFields, type FieldKind, type FieldType, } from './field-types.js';
 /**
  * What an app adds to `.brydio/app.json` to be more than a bundle of servers
@@ -163,9 +164,11 @@ declare const extensionShape: {
             group: z.ZodString;
             minimum: z.ZodOptional<z.ZodNumber>;
         }, z.core.$strict>>;
+        readers: z.ZodOptional<z.ZodString>;
+        editors: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>>>;
     tools: z.ZodOptional<z.ZodObject<{
-        generated: z.ZodOptional<z.ZodBoolean>;
+        generated: z.ZodOptional<z.ZodUnion<readonly [z.ZodBoolean, z.ZodLiteral<"read">]>>;
         custom: z.ZodOptional<z.ZodArray<z.ZodObject<{
             name: z.ZodString;
             description: z.ZodString;
@@ -241,7 +244,7 @@ export interface DataProblem {
     field?: string;
     message: string;
 }
-export type DataProblemCode = FieldTypeInvalid['code'] | OpenProblemCode | ConfirmProblemCode | AnonymousProblemCode | 'data_too_many_collections' | 'data_too_many_fields' | 'data_collection_name_format' | 'data_field_name_format' | 'data_field_reserved' | 'data_label_format' | 'data_label_taken' | 'data_project_field_twice' | 'data_search_unknown_field' | 'data_search_not_text' | 'grant_collection_missing' | 'grant_tool_missing' | 'custom_name_taken' | 'custom_collection_unknown' | 'custom_input_invalid' | 'placement_key_taken' | 'placement_screen_unknown' | 'placement_home_sizes' | 'placement_sizes_not_home' | 'placement_widget_sizes' | 'placement_tab_retired' | 'placement_public_shape' | 'placement_public_nothing' | 'placement_chat_card_shape' | 'grant_tool_cross_app_self' | 'placement_children_too_deep' | 'placement_create_tool_unknown' | 'placement_create_not_write' | 'secret_name_taken' | 'grant_secrets_missing';
+export type DataProblemCode = FieldTypeInvalid['code'] | OpenProblemCode | ConfirmProblemCode | AnonymousProblemCode | ReadersProblemCode | EditorsProblemCode | 'data_too_many_collections' | 'data_too_many_fields' | 'data_collection_name_format' | 'data_field_name_format' | 'data_field_reserved' | 'data_label_format' | 'data_label_taken' | 'data_project_field_twice' | 'data_search_unknown_field' | 'data_search_not_text' | 'grant_collection_missing' | 'grant_tool_missing' | 'custom_name_taken' | 'custom_collection_unknown' | 'custom_input_invalid' | 'placement_key_taken' | 'placement_screen_unknown' | 'placement_home_sizes' | 'placement_sizes_not_home' | 'placement_widget_sizes' | 'placement_tab_retired' | 'placement_public_shape' | 'placement_public_nothing' | 'placement_chat_card_shape' | 'grant_tool_cross_app_self' | 'placement_children_too_deep' | 'placement_create_tool_unknown' | 'placement_create_not_write' | 'secret_name_taken' | 'grant_secrets_missing';
 type Additions = z.infer<z.ZodObject<typeof extensionShape>>;
 /**
  * Everything wrong with an app's additions that a type cannot say.
@@ -340,9 +343,11 @@ export declare const manifestExtensionsSchema: z.ZodObject<{
             group: z.ZodString;
             minimum: z.ZodOptional<z.ZodNumber>;
         }, z.core.$strict>>;
+        readers: z.ZodOptional<z.ZodString>;
+        editors: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>>>;
     tools: z.ZodOptional<z.ZodObject<{
-        generated: z.ZodOptional<z.ZodBoolean>;
+        generated: z.ZodOptional<z.ZodUnion<readonly [z.ZodBoolean, z.ZodLiteral<"read">]>>;
         custom: z.ZodOptional<z.ZodArray<z.ZodObject<{
             name: z.ZodString;
             description: z.ZodString;
@@ -476,9 +481,11 @@ export declare const storedExtensionsSchema: z.ZodObject<{
             group: z.ZodString;
             minimum: z.ZodOptional<z.ZodNumber>;
         }, z.core.$strict>>;
+        readers: z.ZodOptional<z.ZodString>;
+        editors: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>>>;
     tools: z.ZodOptional<z.ZodObject<{
-        generated: z.ZodOptional<z.ZodBoolean>;
+        generated: z.ZodOptional<z.ZodUnion<readonly [z.ZodBoolean, z.ZodLiteral<"read">]>>;
         custom: z.ZodOptional<z.ZodArray<z.ZodObject<{
             name: z.ZodString;
             description: z.ZodString;
@@ -647,9 +654,11 @@ export declare const appManifestSchema: z.ZodObject<{
             group: z.ZodString;
             minimum: z.ZodOptional<z.ZodNumber>;
         }, z.core.$strict>>;
+        readers: z.ZodOptional<z.ZodString>;
+        editors: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>>>;
     tools: z.ZodOptional<z.ZodObject<{
-        generated: z.ZodOptional<z.ZodBoolean>;
+        generated: z.ZodOptional<z.ZodUnion<readonly [z.ZodBoolean, z.ZodLiteral<"read">]>>;
         custom: z.ZodOptional<z.ZodArray<z.ZodObject<{
             name: z.ZodString;
             description: z.ZodString;
@@ -822,9 +831,11 @@ export declare const newAppManifestSchema: z.ZodObject<{
             group: z.ZodString;
             minimum: z.ZodOptional<z.ZodNumber>;
         }, z.core.$strict>>;
+        readers: z.ZodOptional<z.ZodString>;
+        editors: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>>>;
     tools: z.ZodOptional<z.ZodObject<{
-        generated: z.ZodOptional<z.ZodBoolean>;
+        generated: z.ZodOptional<z.ZodUnion<readonly [z.ZodBoolean, z.ZodLiteral<"read">]>>;
         custom: z.ZodOptional<z.ZodArray<z.ZodObject<{
             name: z.ZodString;
             description: z.ZodString;
@@ -914,6 +925,10 @@ export interface CollectionSpec {
     definesFieldsOf?: string;
     /** Answers kept with no writer, read only a whole group of at least `minimum` at a time (P13). */
     anonymous?: AnonymousSpec;
+    /** The string[] field naming who alone may read a record, when it names anyone (P16). */
+    readers?: string;
+    /** The string[] field naming who alone may change a record, when it names anyone (DW06). */
+    editors?: string;
 }
 /**
  * The singular a collection's tools are named with: the manifest's, else the

package/src/schema.js

@@ -5,6 +5,7 @@ import { migrationsSchema } from "./migrations.js";
 import { openSchemaProblems } from "./open-schema.js";
 import { confirmEmailProblems, confirmEmailSchema } from "./confirm-email.js";
 import { anonymousProblems, anonymousSchema, anonymousSpec } from "./anonymous.js";
+import { editorsProblems, editorsSchema, READERS_LIMIT, readersProblems, readersSchema } from "./readers.js";
 export { COLOUR_TOKENS, FIELD_LIMITS, parseFieldType, RESERVED_FIELDS, structuredFields, } from "./field-types.js";
 /**
  * What an app adds to `.brydio/app.json` to be more than a bundle of servers
@@ -152,6 +153,10 @@ const collectionSchema = z.object({
      * batch, a watch and a create naming its own writer.
      */
     anonymous: anonymousSchema.optional(),
+    /** One of its string[] fields: the user ids who alone may read a record, when it names any (P16). */
+    readers: readersSchema.optional(),
+    /** One of its string[] fields: the user ids who alone may change a record, when it names any (DW06). */
+    editors: editorsSchema.optional(),
 });
 const screenSchema = z.object({
     /**
@@ -197,7 +202,12 @@ const customToolSchema = z.object({
 });
 const toolsSchema = z.object({
     /** Off only when the app supplies every tool itself (A3-F08). */
-    generated: z.boolean().optional(),
+    /**
+     * Off only when the app supplies every tool itself. `"read"` keeps the
+     * generated reads (get, list, search) and leaves every write to the app's
+     * own tools, where its rules about who may change what live (DW06).
+     */
+    generated: z.union([z.boolean(), z.literal('read')]).optional(),
     custom: z.array(customToolSchema).max(MAX_CUSTOM_TOOLS).optional(),
 });
 /** Most secrets one app may declare (ADR-A24). */
@@ -389,6 +399,11 @@ export function dataProblems(additions, options = {}) {
     for (const [collection, declared] of collections) {
         problems.push(...anonymousProblems(collection, declared));
     }
+    // A collection whose records name their readers names a list of user ids to keep them in (P16).
+    for (const [collection, declared] of collections) {
+        problems.push(...readersProblems(collection, declared));
+        problems.push(...editorsProblems(collection, declared));
+    }
     // What the app keeps must be what it asks to keep (A3-F06-S01): a
     // collection the grants leave out would be data a workspace never agreed to
     // hold, found only when the first write is refused.
@@ -490,7 +505,7 @@ export function dataProblems(additions, options = {}) {
 function folderProblems(additions) {
     const problems = [];
     const custom = new Map((additions.tools?.custom ?? []).map(tool => [tool.name, tool]));
-    const generatedWrites = additions.tools?.generated === false
+    const generatedWrites = additions.tools?.generated === false || additions.tools?.generated === 'read'
         ? new Set()
         : new Set(Object.entries(additions.data ?? {}).flatMap(([name, declared]) => {
             const label = labelOf(name, declared.label);
@@ -551,15 +566,11 @@ function customToolProblems(additions, options) {
         : new Set(Object.entries(additions.data ?? {}).flatMap(([name, declared]) => {
             const label = labelOf(name, declared.label);
             const plural = `${label}s`;
-            return [
-                `create_${label}`,
-                `update_${label}`,
-                `get_${label}`,
-                `delete_${label}`,
-                `list_${plural}`,
-                `search_${plural}`,
-                `batch_${plural}`,
-            ];
+            const reads = [`get_${label}`, `list_${plural}`, `search_${plural}`];
+            // With only reads generated, the write names are the app's to use.
+            return additions.tools?.generated === 'read'
+                ? reads
+                : [...reads, `create_${label}`, `update_${label}`, `delete_${label}`, `batch_${plural}`];
         }));
     const seen = new Set();
     const granted = additions.grants?.tools ?? [];
@@ -720,7 +731,13 @@ export function collectionsOf(manifest) {
         const tableField = declared.openSchema?.table ?? owner?.flag.table;
         const fields = Object.fromEntries(Object.entries(declared.schema).map(([field, raw]) => {
             const type = parseFieldType(raw);
-            return [field, field === tableField ? { ...type, plain: true } : type];
+            if (field === tableField)
+                return [field, { ...type, plain: true }];
+            // A record's readers or editors may name a whole team (P16, DW06).
+            return [
+                field,
+                (field === declared.readers || field === declared.editors) && type.kind === 'string[]' ? { ...type, maxEntries: READERS_LIMIT } : type,
+            ];
         }));
         const label = labelOf(name, declared.label);
         const names = Object.keys(fields);
@@ -738,6 +755,8 @@ export function collectionsOf(manifest) {
                 : {}),
             ...(owner ? { definesFieldsOf: owner.name } : {}),
             ...(declared.anonymous ? { anonymous: anonymousSpec(declared.anonymous) } : {}),
+            ...(declared.readers ? { readers: declared.readers } : {}),
+            ...(declared.editors ? { editors: declared.editors } : {}),
         };
     });
 }