@friggframework/core 2.0.0--canary.681.2df9ef0.0 → 2.0.0--canary.682.cbca9e2.0

package/modules/scope-config.js

@@ -0,0 +1,155 @@
+/**
+ * Reading and validating ownership settings in an app definition (ADR-056
+ * §3.1, §3.3). Called once by loadAppDefinition, so a bad setting stops the app
+ * at load, not on the first request. No I/O.
+ */
+
+const {
+    SCOPES,
+    INDIVIDUAL_ACROSS_VALUES,
+    OWNER_RULES,
+    configError,
+    isPlainObject,
+    parseScopeSetting,
+    resolveScope,
+} = require('./scope-resolution');
+const { entityTypeNameOf } = require('./entity-type-registry');
+
+/** The binding scope an integration declares for `modules[key]`, if any. */
+function bindingScopeSetting(Definition, key) {
+    const binding = Definition?.modules?.[key];
+    if (binding?.scope !== undefined) return binding.scope;
+    const entityEntry = Definition?.entities?.[key];
+    if (entityEntry?.scope !== undefined) return entityEntry.scope;
+    // Deprecated alias from the global-entities branch: `global: true`.
+    if (entityEntry?.global === true) return SCOPES.GLOBAL;
+    return undefined;
+}
+
+function readAppOwnership(appDefinition) {
+    const raw = appDefinition?.ownership;
+    if (raw === undefined || raw === null) {
+        return { scope: null, individualAcross: 'organization' };
+    }
+    if (!isPlainObject(raw)) {
+        throw configError('appDefinition.ownership', 'must be an object');
+    }
+    const unknown = Object.keys(raw).filter(
+        (key) => key !== 'scope' && key !== 'individualAcross'
+    );
+    if (unknown.length) {
+        throw configError(
+            'appDefinition.ownership',
+            `unknown setting(s): ${unknown.join(', ')}`
+        );
+    }
+    const individualAcross = raw.individualAcross ?? 'organization';
+    if (!INDIVIDUAL_ACROSS_VALUES.includes(individualAcross)) {
+        throw configError(
+            'appDefinition.ownership.individualAcross',
+            `must be one of ${INDIVIDUAL_ACROSS_VALUES.join(', ')}`
+        );
+    }
+    return {
+        scope: parseScopeSetting(raw.scope, 'appDefinition.ownership.scope'),
+        individualAcross,
+    };
+}
+
+function readIntegrationOwnership(integrationClass) {
+    const name = integrationClass?.Definition?.name || 'unnamed';
+    const raw = integrationClass?.Definition?.ownership;
+    if (raw === undefined || raw === null) return { scope: null, owner: 'derive' };
+    const where = `integration '${name}' ownership`;
+    if (!isPlainObject(raw)) throw configError(where, 'must be an object');
+    const unknown = Object.keys(raw).filter(
+        (key) => key !== 'scope' && key !== 'owner'
+    );
+    if (unknown.length) {
+        throw configError(where, `unknown setting(s): ${unknown.join(', ')}`);
+    }
+    const owner = raw.owner ?? 'derive';
+    if (!OWNER_RULES.includes(owner)) {
+        throw configError(where, `owner must be one of ${OWNER_RULES.join(', ')}`);
+    }
+    return { scope: parseScopeSetting(raw.scope, `${where}.scope`), owner };
+}
+
+/**
+ * Every binding of every integration with its resolved scope and where it came
+ * from, parsing each integration's settings once. Throws OwnershipConfigError
+ * for any invalid one. Exported for tooling that wants to show the chain.
+ */
+function listBindingScopes(appDefinition, entityTypeRegistry, primary) {
+    const app = readAppOwnership(appDefinition);
+    const rows = [];
+    for (const integrationClass of appDefinition?.integrations || []) {
+        const Definition = integrationClass?.Definition;
+        const name = Definition?.name || 'unnamed';
+        const ownership = readIntegrationOwnership(integrationClass);
+        for (const [key, binding] of Object.entries(Definition?.modules || {})) {
+            const moduleName = entityTypeNameOf(binding?.definition);
+            const resolved = resolveScope({
+                binding: parseScopeSetting(
+                    bindingScopeSetting(Definition, key),
+                    `integration '${name}' binding '${key}' scope`
+                ),
+                integration: ownership.scope,
+                entityType: moduleName
+                    ? entityTypeRegistry?.get(moduleName)?.settings?.scope
+                    : undefined,
+                app: app.scope,
+                primary,
+            });
+            rows.push({
+                integration: name,
+                binding: key,
+                moduleName: moduleName ?? null,
+                scope: resolved.scope,
+                source: resolved.source,
+                owner: ownership.owner,
+            });
+        }
+    }
+    return rows;
+}
+
+/**
+ * Validates every ownership setting in one pass and returns the app-level
+ * config the runtime needs.
+ *
+ * @returns {{scope: ({default: string, allow: string[]}|null), individualAcross: string}}
+ * @throws {OwnershipConfigError}
+ */
+function resolveOwnershipConfig(appDefinition, entityTypeRegistry) {
+    const app = readAppOwnership(appDefinition);
+    for (const [name, entry] of entityTypeRegistry || []) {
+        parseScopeSetting(entry?.settings?.scope, `entity type '${name}' scope`);
+    }
+    const rows = listBindingScopes(
+        appDefinition,
+        entityTypeRegistry,
+        appDefinition?.user?.primary
+    );
+    // §3.3: a shared integration must not run on one person's credential.
+    for (const row of rows) {
+        if (row.owner === 'organization' && row.scope === SCOPES.INDIVIDUAL) {
+            throw configError(
+                `integration '${row.integration}' binding '${row.binding}'`,
+                "an organization-owned integration cannot bind an 'individual' entity"
+            );
+        }
+    }
+    return Object.freeze({
+        scope: app.scope,
+        individualAcross: app.individualAcross,
+    });
+}
+
+module.exports = {
+    bindingScopeSetting,
+    readAppOwnership,
+    readIntegrationOwnership,
+    listBindingScopes,
+    resolveOwnershipConfig,
+};

package/modules/scope-policy.js

@@ -0,0 +1,80 @@
+/**
+ * The object a use case asks about scopes (ADR-056 §3): the app's ownership
+ * config and entity type registry bound once, as closures. With no arguments it
+ * is the behaviour of an app that configures nothing.
+ */
+
+const {
+    INDIVIDUAL_ACROSS_VALUES,
+    configError,
+    parseScopeSetting,
+    resolveScope,
+    resolveOwnerForScope,
+} = require('./scope-resolution');
+const { accessContext, describeRecord } = require('./scope-visibility');
+
+/**
+ * @param {Object} [params]
+ * @param {{scope: *, individualAcross: string}} [params.ownership] - the raw
+ *   `appDefinition.ownership` or what resolveOwnershipConfig returned (a parsed
+ *   `{ default, allow }` parses to itself)
+ * @param {Map} [params.entityTypeRegistry]
+ */
+function createScopePolicy({ ownership, entityTypeRegistry } = {}) {
+    const appScope = parseScopeSetting(
+        ownership?.scope,
+        'appDefinition.ownership.scope'
+    );
+    const individualAcross = ownership?.individualAcross ?? 'organization';
+    if (!INDIVIDUAL_ACROSS_VALUES.includes(individualAcross)) {
+        throw configError(
+            'appDefinition.ownership.individualAcross',
+            `must be one of ${INDIVIDUAL_ACROSS_VALUES.join(', ')}`
+        );
+    }
+
+    const contextFor = (user) => accessContext(user, { individualAcross });
+
+    /** The scope a new connection of `entityType` gets (levels 1, 4, 5, 6). */
+    const resolveEntityScope = ({ entityType, requestScope, binding, integration, user }) =>
+        resolveScope({
+            request: requestScope,
+            binding,
+            integration,
+            entityType: entityTypeRegistry?.get?.(entityType)?.settings?.scope,
+            app: appScope,
+            primary: user?.config?.primary,
+        });
+
+    /**
+     * Scope, then owner and organization, for a new entity. `legacyOrgId` (the
+     * person's legacy organization pointer) rides along so a later lookup can
+     * reuse an entity written before scoping.
+     */
+    const resolveOwnership = ({ entityType, requestScope, user }) => {
+        const ctx = contextFor(user);
+        const resolved = resolveEntityScope({ entityType, requestScope, user });
+        return {
+            ...resolveOwnerForScope(resolved.scope, ctx),
+            legacyOrgId: ctx.legacyOrgId,
+            source: resolved.source,
+        };
+    };
+
+    /** Whether `user` may load this stored entity for use (same clauses as the list). */
+    const canUseEntity = (user, entity) =>
+        describeRecord(entity, contextFor(user), 'entity') !== null;
+
+    return Object.freeze({
+        individualAcross,
+        accessContext: contextFor,
+        resolveScope: resolveEntityScope,
+        resolveOwnership,
+        canUseEntity,
+    });
+}
+
+/** The policy of an app that configures nothing; what a use case gets by default. */
+const DEFAULT_SCOPE_POLICY = createScopePolicy();
+
+module.exports = { createScopePolicy, DEFAULT_SCOPE_POLICY };

package/modules/scope-resolution.js

@@ -0,0 +1,277 @@
+/**
+ * Scope resolution and ownership on create (ADR-056 §3.1, §3.2, §3.6).
+ *
+ * No I/O: everything here is a function of what it is handed (settings, a
+ * request's identity context, stored rows). This file also holds the shared
+ * constants and `OwnershipConfigError`, so `scope-config.js` (which validates
+ * app definitions) and `scope-visibility.js` can import them without a cycle.
+ *
+ * There is no `scope` column. The owner's user type already says it: no owner
+ * is `global`, the active organization's user is `organization`, the caller's
+ * individual user is `individual` (docs/guides/entity-scopes.md).
+ */
+
+const Boom = require('@hapi/boom');
+const { BaseError } = require('../errors/base-error');
+const { isPresent, sameId } = require('../user/membership');
+
+const SCOPES = Object.freeze({
+    INDIVIDUAL: 'individual',
+    ORGANIZATION: 'organization',
+    GLOBAL: 'global',
+});
+const SCOPE_VALUES = Object.freeze(Object.values(SCOPES));
+const INDIVIDUAL_ACROSS_VALUES = Object.freeze(['organization', 'all']);
+const OWNER_RULES = Object.freeze(['derive', 'individual', 'organization']);
+const ACCESS = Object.freeze({ MANAGE: 'manage', USE: 'use', VIEW: 'view' });
+
+/** Raised at app-definition load for an invalid ownership setting. */
+class OwnershipConfigError extends BaseError {
+    constructor(message, options) {
+        super(message, options);
+        this.code = 'OWNERSHIP_CONFIG_INVALID';
+    }
+}
+
+const isPlainObject = (value) =>
+    value !== null && typeof value === 'object' && !Array.isArray(value);
+
+const configError = (where, message) =>
+    new OwnershipConfigError(`${where}: ${message}`);
+
+/**
+ * One level's setting: a scope (`'organization'`) or a default plus what a
+ * request may choose (`{ default, allow }`). Returns `{ default, allow }`, or
+ * null when the level sets nothing. Idempotent on its own output.
+ */
+function parseScopeSetting(setting, where) {
+    if (setting === undefined || setting === null) return null;
+    if (typeof setting === 'string') {
+        if (!SCOPE_VALUES.includes(setting)) {
+            throw configError(
+                where,
+                `scope '${setting}' is not one of ${SCOPE_VALUES.join(', ')}`
+            );
+        }
+        return { default: setting, allow: [setting] };
+    }
+    if (!isPlainObject(setting)) {
+        throw configError(where, 'scope must be a scope name or { default, allow }');
+    }
+    const unknown = Object.keys(setting).filter(
+        (key) => key !== 'default' && key !== 'allow'
+    );
+    if (unknown.length) {
+        throw configError(where, `unknown scope setting(s): ${unknown.join(', ')}`);
+    }
+    const { allow, default: defaultScope } = setting;
+    if (allow !== undefined) {
+        if (
+            !Array.isArray(allow) ||
+            allow.length === 0 ||
+            allow.some((value) => !SCOPE_VALUES.includes(value)) ||
+            new Set(allow).size !== allow.length
+        ) {
+            throw configError(
+                where,
+                `scope.allow must list one or more of ${SCOPE_VALUES.join(', ')} once each`
+            );
+        }
+    }
+    if (defaultScope !== undefined && !SCOPE_VALUES.includes(defaultScope)) {
+        throw configError(
+            where,
+            `scope.default '${defaultScope}' is not one of ${SCOPE_VALUES.join(', ')}`
+        );
+    }
+    if (defaultScope === undefined && (allow === undefined || allow.length !== 1)) {
+        throw configError(where, 'scope needs a default (or an allow list of exactly one)');
+    }
+    const resolvedDefault = defaultScope ?? allow[0];
+    const resolvedAllow = allow ?? [resolvedDefault];
+    if (!resolvedAllow.includes(resolvedDefault)) {
+        throw configError(
+            where,
+            `scope.default '${resolvedDefault}' must be in scope.allow`
+        );
+    }
+    return { default: resolvedDefault, allow: [...resolvedAllow] };
+}
+
+/** The level-6 default: `organization` for an organization-primary app. */
+const defaultScopeFor = (primary) =>
+    primary === 'organization' ? SCOPES.ORGANIZATION : SCOPES.INDIVIDUAL;
+
+const LEVELS = ['binding', 'integration', 'entityType', 'app'];
+
+/**
+ * The first level that sets a scope (ADR-056 §3.1), each overriding those
+ * below it; nothing intersects. Returns `{ default, allow, source }`.
+ */
+function decideLevel({ binding, integration, entityType, app, primary } = {}) {
+    const settings = { binding, integration, entityType, app };
+    for (const source of LEVELS) {
+        const parsed = parseScopeSetting(settings[source], `${source} scope`);
+        if (parsed) return { ...parsed, source };
+    }
+    const fallback = defaultScopeFor(primary);
+    return { default: fallback, allow: [fallback], source: 'default' };
+}
+
+/**
+ * What a request may choose, from the deciding level's `allow` list only. A
+ * tenant request is never given `global`; a scope outside the list is refused.
+ * Both are the same refusal (403 SCOPE_NOT_ALLOWED): the caller asked for
+ * something this app does not offer.
+ */
+function applyRequest(decided, request) {
+    const result = {
+        scope: decided.default,
+        source: decided.source,
+        decidedBy: decided.source,
+        allow: decided.allow,
+    };
+    if (request === undefined || request === null) return result;
+    if (!SCOPE_VALUES.includes(request)) {
+        throw Boom.badRequest(
+            `scope must be one of ${SCOPE_VALUES.filter((s) => s !== SCOPES.GLOBAL).join(', ')}`,
+            { code: 'SCOPE_INVALID', details: { field: 'scope' } }
+        );
+    }
+    if (request === SCOPES.GLOBAL) {
+        throw Boom.forbidden(
+            'global entities are created by the app owner through admin routes, not by a tenant request',
+            { code: 'SCOPE_NOT_ALLOWED' }
+        );
+    }
+    if (!decided.allow.includes(request)) {
+        throw Boom.forbidden(
+            `scope '${request}' is not allowed here; allowed: ${decided.allow.join(', ')}`,
+            {
+                code: 'SCOPE_NOT_ALLOWED',
+                details: { field: 'scope', allowed: decided.allow },
+            }
+        );
+    }
+    return { ...result, scope: request, source: 'request' };
+}
+
+/**
+ * The scope a new connection gets: decideLevel then applyRequest.
+ *
+ * @param {Object} levels
+ * @param {string} [levels.request] - `scope` on the request
+ * @param {*} [levels.binding] - `use(module, { scope })` / `Definition.entities[key].scope`
+ * @param {*} [levels.integration] - `Definition.ownership.scope`
+ * @param {*} [levels.entityType] - registry `settings.scope` (ADR-059)
+ * @param {*} [levels.app] - `appDefinition.ownership.scope`
+ * @param {string} [levels.primary] - `user.primary`
+ * @returns {{scope: string, source: string, decidedBy: string, allow: string[]}}
+ */
+function resolveScope({ request, ...levels } = {}) {
+    return applyRequest(decideLevel(levels), request);
+}
+
+const MISSING_INDIVIDUAL =
+    'this request has no individual user; send x-frigg-appuserid (or sign in with a token that names the person)';
+const MISSING_ORGANIZATION =
+    'this request has no active organization; send x-frigg-apporgid (or sign in with a token that names the organization)';
+
+const missing = (message, field) =>
+    Boom.badRequest(message, { code: 'IDENTITY_REQUIRED', details: { field } });
+
+/**
+ * The owner and organization for a new entity of `scope` (§3.2):
+ *
+ *   individual   -> the person; the active organization (null under 'all')
+ *   organization -> the active organization's user, in that organization
+ *   global       -> refused here: the tenant API never creates global entities
+ *
+ * `ctx` is an access context (scope-visibility.accessContext).
+ */
+function resolveOwnerForScope(scope, ctx) {
+    if (scope === SCOPES.INDIVIDUAL) {
+        if (!ctx.callerId) throw missing(MISSING_INDIVIDUAL, 'x-frigg-appuserid');
+        return {
+            scope,
+            ownerId: ctx.callerId,
+            organizationId: ctx.individualAcross === 'all' ? null : ctx.activeOrgId,
+        };
+    }
+    if (scope === SCOPES.ORGANIZATION) {
+        if (!ctx.activeOrgId) throw missing(MISSING_ORGANIZATION, 'x-frigg-apporgid');
+        return { scope, ownerId: ctx.activeOrgId, organizationId: ctx.activeOrgId };
+    }
+    throw Boom.forbidden(
+        'global entities are created by the app owner through admin routes, not through the tenant API',
+        { code: 'SCOPE_NOT_ALLOWED' }
+    );
+}
+
+/**
+ * The owner kind of an integration (§3 "Integration ownership"): the
+ * organization when every entity it uses is organization-scoped, otherwise the
+ * person, unless `Definition.ownership.owner` says. ResolveIntegrationOwnership
+ * then refuses an integration whose entities are not all of that one scope.
+ */
+function integrationOwnerKind(entityScopes, rule = 'derive') {
+    if (rule === 'individual' || rule === 'organization') return rule;
+    return entityScopes.length > 0 &&
+        entityScopes.every((scope) => scope === SCOPES.ORGANIZATION)
+        ? SCOPES.ORGANIZATION
+        : SCOPES.INDIVIDUAL;
+}
+
+/**
+ * The owner and organization of a new integration of owner kind `kind`
+ * ('individual' | 'organization').
+ */
+function resolveIntegrationOwner(kind, ctx) {
+    if (kind === SCOPES.ORGANIZATION) {
+        if (!ctx.activeOrgId) throw missing(MISSING_ORGANIZATION, 'x-frigg-apporgid');
+        return { ownerId: ctx.activeOrgId, organizationId: ctx.activeOrgId };
+    }
+    if (!ctx.callerId) throw missing(MISSING_INDIVIDUAL, 'x-frigg-appuserid');
+    return { ownerId: ctx.callerId, organizationId: ctx.activeOrgId };
+}
+
+/**
+ * The entity an authorization should reuse. The same provider account in two
+ * organizations is two entities (§3.6), so an exact organization match wins.
+ * A legacy row (organizationId null, written before scoping) is reused when
+ * the visibility rule would show it here: an organization-owned one always
+ * (the owner is unambiguous), an individual one only in the person's legacy
+ * organization.
+ */
+function pickExistingEntity(candidates, { scope, organizationId, legacyOrgId }) {
+    const rows = candidates || [];
+    const unscoped = (row) => !isPresent(row.organizationId);
+    const exact = rows.find((row) =>
+        isPresent(organizationId)
+            ? sameId(row.organizationId, organizationId)
+            : unscoped(row)
+    );
+    if (exact) return exact;
+    const legacyApplies =
+        scope === SCOPES.ORGANIZATION || sameId(legacyOrgId, organizationId);
+    return legacyApplies ? rows.find(unscoped) ?? null : null;
+}
+
+module.exports = {
+    SCOPES,
+    SCOPE_VALUES,
+    INDIVIDUAL_ACROSS_VALUES,
+    OWNER_RULES,
+    ACCESS,
+    OwnershipConfigError,
+    configError,
+    isPlainObject,
+    parseScopeSetting,
+    decideLevel,
+    applyRequest,
+    resolveScope,
+    resolveOwnerForScope,
+    integrationOwnerKind,
+    resolveIntegrationOwner,
+    pickExistingEntity,
+};

package/modules/scope-visibility.js

@@ -0,0 +1,165 @@
+/**
+ * Which stored rows a caller may see and use (ADR-056 §3.4, §3.6).
+ *
+ * No I/O. One clause list (`ctx.clauses`) is what a repository is asked for and
+ * what `describeRecord` checks every returned row against, so a list and an
+ * access check cannot drift apart. The clauses are built once per request, when
+ * the access context is.
+ */
+
+const { isPresent, idString, sameId } = require('../user/membership');
+const { SCOPES, ACCESS } = require('./scope-resolution');
+
+/**
+ * One owner/organization pair a repository ORs into a single query.
+ * `userId` is the owner's user id, and for an organization-owned row that is
+ * the ORGANIZATION user's id, not a person's. `organizationId: null` means "has
+ * no organization" (unset or null); otherwise the id of the organization.
+ *
+ * @typedef {Object} OwnershipClause
+ * @property {string} userId
+ * @property {(string|null)} organizationId
+ */
+
+/**
+ * Whether the caller's own rows with no organization belong to the context this
+ * request acts in: always when it acts in no organization (today's behaviour),
+ * always for an entity under `individualAcross: 'all'`, and otherwise only in
+ * the person's legacy organization.
+ */
+function unscopedRowsBelongHere(base, kind) {
+    return (
+        !base.activeOrgId ||
+        (kind === 'entity' && base.individualAcross === 'all') ||
+        sameId(base.legacyOrgId, base.activeOrgId)
+    );
+}
+
+/**
+ * What a caller may see, as owner/organization pairs:
+ *
+ *   - the active organization's own rows (owner = the organization), whether
+ *     they carry its id or, written before scoping, none;
+ *   - the caller's rows in the active organization;
+ *   - the caller's rows with no organization, when `unscopedRowsBelongHere`.
+ *
+ * `kind` is 'entity' or 'integration'; only entities may be
+ * organization-independent under 'all' (an integration always belongs to the
+ * organization it was created in).
+ *
+ * @returns {OwnershipClause[]}
+ */
+function buildClauses(base, kind) {
+    const clauses = [];
+    if (base.activeOrgId) {
+        clauses.push({ userId: base.activeOrgId, organizationId: base.activeOrgId });
+        clauses.push({ userId: base.activeOrgId, organizationId: null });
+    }
+    if (base.callerId) {
+        if (base.activeOrgId) {
+            clauses.push({ userId: base.callerId, organizationId: base.activeOrgId });
+        }
+        if (unscopedRowsBelongHere(base, kind)) {
+            clauses.push({ userId: base.callerId, organizationId: null });
+        }
+    }
+    return clauses;
+}
+
+/**
+ * Who the caller is, for ownership and visibility: their individual user, the
+ * organization this request acts in, the legacy `organizationId` pointer, and
+ * the clauses that follow from them (computed once).
+ *
+ * @param {Object} user - the authenticated `User` (or a `{ getId }` double)
+ * @param {{individualAcross?: string}} [options]
+ */
+function accessContext(user, { individualAcross = 'organization' } = {}) {
+    const hasUserModel = typeof user?.getIndividualUser === 'function';
+    const individual = hasUserModel ? user.getIndividualUser() : null;
+    const base = {
+        callerId: hasUserModel ? idString(individual?.id) : idString(user?.getId?.()),
+        activeOrgId:
+            typeof user?.getActiveOrganizationId === 'function'
+                ? idString(user.getActiveOrganizationId())
+                : null,
+        legacyOrgId: idString(individual?.organizationId),
+        individualAcross,
+    };
+    return {
+        ...base,
+        clauses: {
+            entity: buildClauses(base, 'entity'),
+            integration: buildClauses(base, 'integration'),
+        },
+    };
+}
+
+/** The clauses for `kind` ('entity' | 'integration'): what to ask the repository. */
+const visibilityClauses = (ctx, kind) => ctx.clauses[kind];
+
+const matchesClause = (record, clause) =>
+    sameId(record.userId, clause.userId) &&
+    (clause.organizationId === null
+        ? !isPresent(record.organizationId)
+        : sameId(record.organizationId, clause.organizationId));
+
+/** The scope a stored row has for this caller, from its owner. */
+function scopeOf(record, ctx) {
+    if (!isPresent(record?.userId)) return SCOPES.GLOBAL;
+    if (sameId(record.userId, ctx.activeOrgId)) return SCOPES.ORGANIZATION;
+    if (sameId(record.userId, ctx.callerId)) return SCOPES.INDIVIDUAL;
+    return null;
+}
+
+const accessFor = (scope) =>
+    scope === SCOPES.GLOBAL ? ACCESS.USE : ACCESS.MANAGE;
+
+/**
+ * What a row is to this caller, or null when they may not see it.
+ * `{ scope, owner: {type, id}, organizationId, access }` (§3.4). A `global`
+ * row is never described: it is not the tenant's to see.
+ */
+function describeRecord(record, ctx, kind) {
+    if (!record) return null;
+    const scope = scopeOf(record, ctx);
+    if (scope === null || scope === SCOPES.GLOBAL) return null;
+    if (!ctx.clauses[kind].some((clause) => matchesClause(record, clause))) {
+        return null;
+    }
+    return {
+        scope,
+        owner: { type: scope, id: idString(record.userId) },
+        organizationId:
+            scope === SCOPES.ORGANIZATION
+                ? idString(record.userId)
+                : idString(record.organizationId),
+        access: accessFor(scope),
+    };
+}
+
+/** `?owner=` values and the scope each one means. */
+const LIST_OWNERS = Object.freeze({
+    me: SCOPES.INDIVIDUAL,
+    org: SCOPES.ORGANIZATION,
+});
+
+/** Whether a described row passes `?scope=` and `?owner=`. */
+function matchesListFilters(description, { scope, owner } = {}) {
+    if (scope !== undefined && description.scope !== scope) return false;
+    if (owner !== undefined && description.owner.type !== LIST_OWNERS[owner]) {
+        return false;
+    }
+    return true;
+}
+
+module.exports = {
+    accessContext,
+    unscopedRowsBelongHere,
+    visibilityClauses,
+    matchesClause,
+    scopeOf,
+    describeRecord,
+    LIST_OWNERS,
+    matchesListFilters,
+};

package/modules/tests/doubles/ownership-matching.js

@@ -0,0 +1,18 @@
+/**
+ * Test double helper: answers an owner/organization clause the way a database
+ * does, so in-memory repositories run the clauses a use case hands them.
+ * `clause.organizationId === null` matches a row with no organization (unset
+ * or null).
+ */
+const same = (a, b) =>
+    a !== undefined && a !== null && b !== undefined && b !== null && String(a) === String(b);
+
+const matchesClause = (row, clause) =>
+    same(row.userId, clause.userId) &&
+    (clause.organizationId === null
+        ? row.organizationId === null || row.organizationId === undefined
+        : same(row.organizationId, clause.organizationId));
+
+const matchesAnyClause = (row, clauses) => clauses.some((clause) => matchesClause(row, clause));
+
+module.exports = { same, matchesClause, matchesAnyClause };