@stonyx/orm 0.3.2-beta.16 → 0.3.2-beta.160

package/dist/dynamodb/operation-builder.js

@@ -0,0 +1,116 @@
+/**
+ * DynamoDB operation parameter builders.
+ *
+ * Each function returns a plain-object "params" bag that can be passed
+ * directly to the corresponding DocumentClient command
+ * (PutCommand, GetCommand, UpdateCommand, DeleteCommand, ScanCommand, QueryCommand).
+ *
+ * All functions are pure — no SDK imports here; the caller wraps params
+ * in the appropriate Command class.
+ */
+/**
+ * PutItem — optionally with a condition expression.
+ *
+ * Pass conditionExpression = 'attribute_not_exists(id)' to enforce uniqueness.
+ */
+export function buildPutItem(tableName, item, conditionExpression) {
+    const params = { TableName: tableName, Item: item };
+    if (conditionExpression)
+        params.ConditionExpression = conditionExpression;
+    return params;
+}
+/**
+ * GetItem by primary key.
+ */
+export function buildGetItem(tableName, key) {
+    return { TableName: tableName, Key: key };
+}
+/**
+ * UpdateItem with a SET expression built from the `updates` object.
+ * Only the supplied attributes are updated (diff-based call site).
+ */
+export function buildUpdateItem(tableName, key, updates) {
+    const names = {};
+    const values = {};
+    const setClauses = [];
+    for (const [attr, val] of Object.entries(updates)) {
+        const nameAlias = `#${attr}`;
+        const valAlias = `:${attr}`;
+        names[nameAlias] = attr;
+        values[valAlias] = val;
+        setClauses.push(`${nameAlias} = ${valAlias}`);
+    }
+    return {
+        TableName: tableName,
+        Key: key,
+        UpdateExpression: `SET ${setClauses.join(', ')}`,
+        ExpressionAttributeNames: names,
+        ExpressionAttributeValues: values,
+        ReturnValues: 'NONE',
+    };
+}
+/**
+ * DeleteItem by primary key.
+ */
+export function buildDeleteItem(tableName, key) {
+    return { TableName: tableName, Key: key };
+}
+/**
+ * ScanCommand params.
+ * If conditions are supplied they are rendered as a FilterExpression using AND.
+ */
+export function buildScan(tableName, conditions, exclusiveStartKey) {
+    const params = { TableName: tableName };
+    if (exclusiveStartKey)
+        params.ExclusiveStartKey = exclusiveStartKey;
+    if (conditions && Object.keys(conditions).length > 0) {
+        const validEntries = Object.entries(conditions).filter(([, val]) => val !== undefined && val !== null);
+        if (validEntries.length > 0) {
+            const names = {};
+            const values = {};
+            const clauses = [];
+            for (const [attr, val] of validEntries) {
+                const nameAlias = `#${attr}`;
+                const valAlias = `:${attr}`;
+                names[nameAlias] = attr;
+                values[valAlias] = val;
+                clauses.push(`${nameAlias} = ${valAlias}`);
+            }
+            params.FilterExpression = clauses.join(' AND ');
+            params.ExpressionAttributeNames = names;
+            params.ExpressionAttributeValues = values;
+        }
+    }
+    return params;
+}
+/**
+ * QueryCommand params for a GSI.
+ * keyConditions must be in the form { attrName: value } and will be rendered
+ * as equality expressions joined by AND.
+ */
+export function buildQuery(tableName, indexName, keyConditions, exclusiveStartKey) {
+    const validEntries = Object.entries(keyConditions).filter(([, val]) => val !== undefined && val !== null);
+    if (validEntries.length === 0) {
+        throw new Error('buildQuery: all keyCondition values are undefined/null');
+    }
+    const names = {};
+    const values = {};
+    const clauses = [];
+    for (const [attr, val] of validEntries) {
+        const nameAlias = `#${attr}`;
+        const valAlias = `:${attr}`;
+        names[nameAlias] = attr;
+        values[valAlias] = val;
+        clauses.push(`${nameAlias} = ${valAlias}`);
+    }
+    const params = {
+        TableName: tableName,
+        IndexName: indexName,
+        KeyConditionExpression: clauses.join(' AND '),
+        ExpressionAttributeNames: names,
+        ExpressionAttributeValues: values,
+    };
+    if (exclusiveStartKey)
+        params.ExclusiveStartKey = exclusiveStartKey;
+    return params;
+}

package/dist/dynamodb/type-map.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Maps ORM attribute types to DynamoDB scalar attribute types.
+ * DynamoDB DocumentClient auto-marshalls JS objects, so most values
+ * are sent as their native JS types.  This map is used by the
+ * schema-introspector and startup provisioner for table/GSI creation.
+ */
+export type DynamoScalarType = 'S' | 'N' | 'BOOL';
+/**
+ * DynamoDB attribute-type string for a given ORM attr type.
+ * - string            → S
+ * - number / float    → N  (stored as Number; DocumentClient handles it)
+ * - boolean           → BOOL
+ * - date              → S  (ISO-8601 string — enables range queries)
+ * - timestamp         → N  (milliseconds since epoch)
+ * - passthrough/trim/etc → S  (safe default)
+ *
+ * For key schema declarations only `S` and `N` are valid; BOOL
+ * is legal for attributes but never for a PK/SK.
+ */
+declare const typeMap: Record<string, DynamoScalarType>;
+/**
+ * Returns the DynamoDB attribute type for a given ORM type string.
+ * Defaults to 'S' for any unknown/custom type.
+ */
+export declare function getDynamoType(attrType: string): DynamoScalarType;
+/**
+ * Returns the DynamoDB key type ('S' | 'N') for use in KeySchema.
+ * BOOL cannot be a key attribute; anything that maps to BOOL falls back to 'S'.
+ */
+export declare function getDynamoKeyType(attrType: string): 'S' | 'N';
+export default typeMap;

package/dist/dynamodb/type-map.js

@@ -0,0 +1,48 @@
+/**
+ * Maps ORM attribute types to DynamoDB scalar attribute types.
+ * DynamoDB DocumentClient auto-marshalls JS objects, so most values
+ * are sent as their native JS types.  This map is used by the
+ * schema-introspector and startup provisioner for table/GSI creation.
+ */
+/**
+ * DynamoDB attribute-type string for a given ORM attr type.
+ * - string            → S
+ * - number / float    → N  (stored as Number; DocumentClient handles it)
+ * - boolean           → BOOL
+ * - date              → S  (ISO-8601 string — enables range queries)
+ * - timestamp         → N  (milliseconds since epoch)
+ * - passthrough/trim/etc → S  (safe default)
+ *
+ * For key schema declarations only `S` and `N` are valid; BOOL
+ * is legal for attributes but never for a PK/SK.
+ */
+const typeMap = {
+    string: 'S',
+    number: 'N',
+    float: 'N',
+    boolean: 'BOOL',
+    date: 'S',
+    timestamp: 'N',
+    passthrough: 'S',
+    trim: 'S',
+    uppercase: 'S',
+    ceil: 'N',
+    floor: 'N',
+    round: 'N',
+};
+/**
+ * Returns the DynamoDB attribute type for a given ORM type string.
+ * Defaults to 'S' for any unknown/custom type.
+ */
+export function getDynamoType(attrType) {
+    return typeMap[attrType] ?? 'S';
+}
+/**
+ * Returns the DynamoDB key type ('S' | 'N') for use in KeySchema.
+ * BOOL cannot be a key attribute; anything that maps to BOOL falls back to 'S'.
+ */
+export function getDynamoKeyType(attrType) {
+    const t = getDynamoType(attrType);
+    return t === 'N' ? 'N' : 'S';
+}
+export default typeMap;

package/dist/hooks.d.ts

@@ -20,7 +20,21 @@ export interface HookContext {
     state?: Record<string, unknown>;
     /** Previous record state (available in update hooks). */
     oldState?: unknown;
-    /** Target record ID for single-record operations. */
+    /**
+     * Target record ID for single-record operations.
+     *
+     * SET ONLY UNDER `delete`. `_withHooks` assigns this key in the two
+     * `operation === 'delete'` branches and nowhere else, so on `get`, `list`,
+     * `create` and `update` the key is ABSENT -- not `undefined`-valued, absent.
+     * A hook rule written as `ctx.recordId === '<id>'` never fires on an update;
+     * the addressed id is in `ctx.params`. Tracked as abofs/stonyx-orm#242.
+     *
+     * @see AccessContext.recordId in ./types/orm-types.ts -- an identically-named
+     * key on an identically-shaped context object, and NOT interchangeable with
+     * this one: it is present on every route `auth()` classifies, and spells
+     * absence as `null` rather than `undefined`. They differ in coverage on four
+     * of five operations, not only in the absence spelling.
+     */
     recordId?: string | number;
     /** Response data (available in after hooks). */
     response?: unknown;

package/dist/index.d.ts

@@ -9,6 +9,9 @@ import { count, avg, sum, min, max } from './aggregates.js';
 export { default } from './main.js';
 export { store, relationships } from './main.js';
 export type { PersistErrorDetail } from './main.js';
+export type { AccessContext, AccessFunction, AccessMethod, AccessOperation } from './types/orm-types.js';
+export type { LinkageFilter } from './types/orm-types.js';
+export { createLinkageFilter } from './access-verdict.js';
 export { Model, View, Serializer };
 export { attr, belongsTo, hasMany, createRecord, updateRecord };
 export { count, avg, sum, min, max };

package/dist/index.js

@@ -23,6 +23,14 @@ import { createRecord, updateRecord } from './manage-record.js';
 import { count, avg, sum, min, max } from './aggregates.js';
 export { default } from './main.js';
 export { store, relationships } from './main.js';
+// The request-scoped linkage-verdict factory (#234). PUBLIC on purpose: the
+// README tells a consumer serializing a `Record` outside the REST layer to pass
+// their own resolved `linkage` option, and without an exported factory the only
+// way to follow that advice is to write a SECOND reading of `access()` in
+// consumer code -- the exact "unreviewed second authorization vocabulary" that
+// src/access-verdict.ts exists to prevent, reproduced where no reviewer sees it
+// drift. Give them the one interpreter instead of an invitation to fork it.
+export { createLinkageFilter } from './access-verdict.js';
 export { Model, View, Serializer }; // base classes
 export { attr, belongsTo, hasMany, createRecord, updateRecord }; // helpers
 export { count, avg, sum, min, max }; // aggregate helpers

package/dist/main.d.ts

@@ -1,4 +1,5 @@
 import Store from './store.js';
+import type { AccessFunction } from './types/orm-types.js';
 interface OrmOptions {
     dbType?: string;
 }
@@ -32,12 +33,127 @@ export default class Orm {
     views: Record<string, unknown>;
     transforms: Record<string, (value: unknown) => unknown>;
     warnings: Set<string>;
+    /**
+     * Model name -> the `access` predicate of the access class that CLAIMS that
+     * model (abofs/stonyx-orm#202).
+     *
+     * Not "that model's own predicate". One access class may claim many models
+     * -- `GlobalAccess` in this repo's fixtures declares five, and `models = '*'`
+     * claims every model in the store -- and it declares ONE `access` method, so
+     * the same function object is registered under every one of those keys.
+     * `getAccess('owner') === getAccess('animal')` is `true` there. The
+     * one-to-one guarantee below is key -> function, never function -> model,
+     * and a caller must not read a resolved predicate as being animal-specific.
+     * What makes the ANSWER model-specific is the context the caller passes and
+     * the predicate actually reading it -- see {@link Orm#getAccess}.
+     *
+     * NAMED FOR WHAT IT HOLDS. It was `accessFiles` through review, inherited
+     * from the function-local in `setup-rest-server.ts` where the values came
+     * straight out of `forEachFileImport` and "files" was defensible. The values
+     * are `AccessFunction`s, and the sibling public registries on this class
+     * (`models`, `serializers`, `views`, `transforms`) are all plural nouns of
+     * the thing held. Renamed here because #202 is the last moment it is free.
+     *
+     * Populated by `setup-rest-server.ts` at boot, from the access classes under
+     * `config.orm.paths.access`, BEFORE any route is mounted -- so it is complete
+     * and reachable before the first request can be served. The mapping is
+     * one-to-one by construction: setup-rest-server throws if two access classes
+     * claim the same model.
+     *
+     * Keys are model names as declared and stored (kebab-case, e.g.
+     * `'phone-number'`), NOT pluralised or mount-prefixed route names.
+     *
+     * WHY THIS EXISTS AS A FIELD. It used to be a function-local in
+     * setup-rest-server that was discarded when that function returned, so at
+     * request time there was no way to get from a model name to that model's
+     * predicate at all. Each `OrmRequest` held only its OWN model's predicate.
+     * That made cross-model authorization -- asking model X's predicate about a
+     * request routed to model Y -- inexpressible, which is the capability
+     * abofs/stonyx-orm#196 and abofs/stonyx-orm#207 are built on.
+     *
+     * Empty when the REST server is disabled, and PARTIAL when one access file
+     * failed to load (`setup-rest-server.ts` catches, warns and assigns whatever
+     * it had). So a missing key does NOT mean the model has no access class.
+     * Prefer {@link Orm#getAccess} over indexing this directly -- it is guarded
+     * against the prototype chain and this is not.
+     */
+    accessFunctions: Record<string, AccessFunction>;
     options: OrmOptions;
     sqlDb?: SqlDb;
     db?: OrmDB | SqlDb;
     private _persistErrorHandler;
     constructor(options?: OrmOptions);
     init(): Promise<void>;
+    /**
+     * Resolve the `access` predicate registered for a model name
+     * (abofs/stonyx-orm#202).
+     *
+     * This is the supported way to reach another model's predicate while
+     * servicing a request routed to a different model. Call it with the model
+     * name and invoke the result with the live request and an explicit context
+     * naming THAT model:
+     *
+     * ```js
+     * const predicate = Orm.instance.getAccess('animal');
+     * if (!predicate) return deny;
+     * const verdict = predicate(request, { model: 'animal', operation: 'read' });
+     * ```
+     *
+     * WHAT IT RESOLVES. The predicate of the access CLASS that claims the model,
+     * which is not necessarily specific to it: one class may claim many models
+     * and declares one `access` method, so
+     * `getAccess('owner') === getAccess('animal')` is `true` against this repo's
+     * fixture. See {@link Orm#accessFunctions}.
+     *
+     * `undefined` means NO PREDICATE COULD BE RESOLVED for that name. That
+     * includes a model whose access class failed to LOAD -- `setup-rest-server`
+     * catches, warns and publishes the partial map -- so it is not the same claim
+     * as "this model is unrestricted". Treat it as DENY, the same way
+     * `AccessContext.operation === undefined` is treated.
+     *
+     * PASSING THE CONTEXT MAKES A MODEL-CORRECT ANSWER POSSIBLE. It does not, on
+     * its own, make the answer model-correct: the resolved predicate has to READ
+     * the context. Measured against this repo's shipped access class on a request
+     * express dispatched to `GET /owners/angela`, asked about ANIMALS:
+     *
+     * ```
+     * getAccess('animal')(ownersRequest, { model: 'animal', operation: 'read' })
+     *   ->  record => record.id !== 'angela' && record.id !== 'restricted'
+     * ```
+     *
+     * The OWNERS filter, which returns `true` for animal 21 -- the record hidden
+     * on every animal surface. Under a mount that predicate recognises neither
+     * way it falls through to `['read', 'create', 'update', 'delete']`, a full
+     * CRUD grant. Either way: context supplied, answer not the animal answer,
+     * wrong in the GRANTING direction, because that predicate is arity-1 and
+     * identifies its collection from the request. AC9 asserts the first case on a
+     * live dispatch.
+     *
+     * Every predicate in this repo and in every consumer tree is arity-1 today,
+     * and there is no supported way for the caller to tell which kind it got; the
+     * boot-time arity warning that would surface it is abofs/stonyx-orm#213. Pass
+     * the context, and do not treat a resolved predicate's answer as
+     * model-specific until that predicate reads it.
+     *
+     * OWN PROPERTIES ONLY. A bare `this.accessFunctions[modelName]` walks the
+     * prototype chain, so `getAccess('constructor')` resolved `Object` and
+     * `getAccess('toString')` resolved `Object.prototype.toString` -- both
+     * callable, and the documented `predicate?.(request, ctx)` pattern then
+     * returned a TRUTHY value (`Object(request)` is the request), bypassing the
+     * `undefined`-means-deny contract entirely. Nothing in the ORM calls
+     * `getAccess` yet, so it was not exploitable as shipped -- but #207 takes the
+     * model name from the REQUEST BODY (`data.relationships.<key>.data.type`),
+     * which would have made a one-field body an authorization bypass. Guarded
+     * here at the read point rather than by constructing the map with a null
+     * prototype, because the field is public and reassignable and the guard has
+     * to hold whatever object it is holding.
+     *
+     * @param modelName - Model name as declared and stored (kebab-case).
+     * @returns The predicate, or `undefined` when no predicate could be resolved
+     *   for that name. `undefined` is NOT "this model is unrestricted" -- see the
+     *   note above. Treat it as deny.
+     */
+    getAccess(modelName: string): AccessFunction | undefined;
     startup(): Promise<void>;
     shutdown(): Promise<void>;
     static get db(): OrmDB | SqlDb;

package/dist/main.js

@@ -38,6 +38,51 @@ export default class Orm {
     views = {};
     transforms = { ...baseTransforms };
     warnings = new Set();
+    /**
+     * Model name -> the `access` predicate of the access class that CLAIMS that
+     * model (abofs/stonyx-orm#202).
+     *
+     * Not "that model's own predicate". One access class may claim many models
+     * -- `GlobalAccess` in this repo's fixtures declares five, and `models = '*'`
+     * claims every model in the store -- and it declares ONE `access` method, so
+     * the same function object is registered under every one of those keys.
+     * `getAccess('owner') === getAccess('animal')` is `true` there. The
+     * one-to-one guarantee below is key -> function, never function -> model,
+     * and a caller must not read a resolved predicate as being animal-specific.
+     * What makes the ANSWER model-specific is the context the caller passes and
+     * the predicate actually reading it -- see {@link Orm#getAccess}.
+     *
+     * NAMED FOR WHAT IT HOLDS. It was `accessFiles` through review, inherited
+     * from the function-local in `setup-rest-server.ts` where the values came
+     * straight out of `forEachFileImport` and "files" was defensible. The values
+     * are `AccessFunction`s, and the sibling public registries on this class
+     * (`models`, `serializers`, `views`, `transforms`) are all plural nouns of
+     * the thing held. Renamed here because #202 is the last moment it is free.
+     *
+     * Populated by `setup-rest-server.ts` at boot, from the access classes under
+     * `config.orm.paths.access`, BEFORE any route is mounted -- so it is complete
+     * and reachable before the first request can be served. The mapping is
+     * one-to-one by construction: setup-rest-server throws if two access classes
+     * claim the same model.
+     *
+     * Keys are model names as declared and stored (kebab-case, e.g.
+     * `'phone-number'`), NOT pluralised or mount-prefixed route names.
+     *
+     * WHY THIS EXISTS AS A FIELD. It used to be a function-local in
+     * setup-rest-server that was discarded when that function returned, so at
+     * request time there was no way to get from a model name to that model's
+     * predicate at all. Each `OrmRequest` held only its OWN model's predicate.
+     * That made cross-model authorization -- asking model X's predicate about a
+     * request routed to model Y -- inexpressible, which is the capability
+     * abofs/stonyx-orm#196 and abofs/stonyx-orm#207 are built on.
+     *
+     * Empty when the REST server is disabled, and PARTIAL when one access file
+     * failed to load (`setup-rest-server.ts` catches, warns and assigns whatever
+     * it had). So a missing key does NOT mean the model has no access class.
+     * Prefer {@link Orm#getAccess} over indexing this directly -- it is guarded
+     * against the prototype chain and this is not.
+     */
+    accessFunctions = {};
     options;
     sqlDb;
     db;
@@ -54,6 +99,10 @@ export default class Orm {
         Orm.instance = this;
     }
     async init() {
+        // Self-register so log.db works even when @stonyx/orm is in the
+        // consumer's `dependencies` (stonyx loader only merges devDependencies).
+        const { logColor = 'white', logMethod = 'db' } = config.orm;
+        log.defineType(logMethod, logColor);
         const { paths, restServer } = config.orm;
         const promises = ['Model', 'Serializer', 'Transform'].map(type => {
             const lowerCaseType = type.toLowerCase();
@@ -115,6 +164,12 @@ export default class Orm {
             this.db = this.sqlDb;
             promises.push(this.sqlDb.init());
         }
+        else if (config.orm.dynamodb) {
+            const { default: DynamoDBDB } = await import('./dynamodb/dynamodb-db.js');
+            this.sqlDb = new DynamoDBDB();
+            this.db = this.sqlDb;
+            promises.push(this.sqlDb.init());
+        }
         else if (this.options.dbType !== 'none') {
             const db = new DB();
             this.db = db;
@@ -135,6 +190,80 @@ export default class Orm {
         Orm.ready = await Promise.all(promises);
         Orm.initialized = true;
     }
+    /**
+     * Resolve the `access` predicate registered for a model name
+     * (abofs/stonyx-orm#202).
+     *
+     * This is the supported way to reach another model's predicate while
+     * servicing a request routed to a different model. Call it with the model
+     * name and invoke the result with the live request and an explicit context
+     * naming THAT model:
+     *
+     * ```js
+     * const predicate = Orm.instance.getAccess('animal');
+     * if (!predicate) return deny;
+     * const verdict = predicate(request, { model: 'animal', operation: 'read' });
+     * ```
+     *
+     * WHAT IT RESOLVES. The predicate of the access CLASS that claims the model,
+     * which is not necessarily specific to it: one class may claim many models
+     * and declares one `access` method, so
+     * `getAccess('owner') === getAccess('animal')` is `true` against this repo's
+     * fixture. See {@link Orm#accessFunctions}.
+     *
+     * `undefined` means NO PREDICATE COULD BE RESOLVED for that name. That
+     * includes a model whose access class failed to LOAD -- `setup-rest-server`
+     * catches, warns and publishes the partial map -- so it is not the same claim
+     * as "this model is unrestricted". Treat it as DENY, the same way
+     * `AccessContext.operation === undefined` is treated.
+     *
+     * PASSING THE CONTEXT MAKES A MODEL-CORRECT ANSWER POSSIBLE. It does not, on
+     * its own, make the answer model-correct: the resolved predicate has to READ
+     * the context. Measured against this repo's shipped access class on a request
+     * express dispatched to `GET /owners/angela`, asked about ANIMALS:
+     *
+     * ```
+     * getAccess('animal')(ownersRequest, { model: 'animal', operation: 'read' })
+     *   ->  record => record.id !== 'angela' && record.id !== 'restricted'
+     * ```
+     *
+     * The OWNERS filter, which returns `true` for animal 21 -- the record hidden
+     * on every animal surface. Under a mount that predicate recognises neither
+     * way it falls through to `['read', 'create', 'update', 'delete']`, a full
+     * CRUD grant. Either way: context supplied, answer not the animal answer,
+     * wrong in the GRANTING direction, because that predicate is arity-1 and
+     * identifies its collection from the request. AC9 asserts the first case on a
+     * live dispatch.
+     *
+     * Every predicate in this repo and in every consumer tree is arity-1 today,
+     * and there is no supported way for the caller to tell which kind it got; the
+     * boot-time arity warning that would surface it is abofs/stonyx-orm#213. Pass
+     * the context, and do not treat a resolved predicate's answer as
+     * model-specific until that predicate reads it.
+     *
+     * OWN PROPERTIES ONLY. A bare `this.accessFunctions[modelName]` walks the
+     * prototype chain, so `getAccess('constructor')` resolved `Object` and
+     * `getAccess('toString')` resolved `Object.prototype.toString` -- both
+     * callable, and the documented `predicate?.(request, ctx)` pattern then
+     * returned a TRUTHY value (`Object(request)` is the request), bypassing the
+     * `undefined`-means-deny contract entirely. Nothing in the ORM calls
+     * `getAccess` yet, so it was not exploitable as shipped -- but #207 takes the
+     * model name from the REQUEST BODY (`data.relationships.<key>.data.type`),
+     * which would have made a one-field body an authorization bypass. Guarded
+     * here at the read point rather than by constructing the map with a null
+     * prototype, because the field is public and reassignable and the guard has
+     * to hold whatever object it is holding.
+     *
+     * @param modelName - Model name as declared and stored (kebab-case).
+     * @returns The predicate, or `undefined` when no predicate could be resolved
+     *   for that name. `undefined` is NOT "this model is unrestricted" -- see the
+     *   note above. Treat it as deny.
+     */
+    getAccess(modelName) {
+        if (!Object.hasOwn(this.accessFunctions, modelName))
+            return undefined;
+        return this.accessFunctions[modelName];
+    }
     async startup() {
         if (this.sqlDb)
             await this.sqlDb.startup();