@friggframework/core 2.0.0--canary.680.daae24e.0 → 2.0.0--canary.686.e94de4d.0

package/queues/queue-provider-factory.js

@@ -0,0 +1,101 @@
+/**
+ * Queue Provider Factory
+ *
+ * Creates a QueueProvider (send / batchSend / parseEvent) for the active
+ * platform. From friggframework/frigg#545, adapted: #545 resolved every
+ * provider through resolveProvider(), so an AWS app had to install
+ * @friggframework/provider-aws. In this stack the AWS SDK is a core
+ * dependency, so the built-in queues are created here and only an unknown
+ * name goes through the provider plugin system.
+ *
+ * Priority order for determining the provider:
+ * 1. Explicit `provider` option
+ * 2. `appDefinition.queue.provider`
+ * 3. `QUEUE_PROVIDER` environment variable
+ * 4. Default: SQS
+ *
+ * Built-in names:
+ * - 'sqs' | 'aws'                     -> SqsQueueProvider
+ * - 'netlify-background' | 'netlify'  -> NetlifyBackgroundProvider
+ * - 'qstash'                          -> QStashQueueProvider
+ * Any other name -> require('@friggframework/provider-<name>').QueueProvider
+ */
+
+const QUEUE_PROVIDERS = {
+    SQS: 'sqs',
+    NETLIFY_BACKGROUND: 'netlify-background',
+    QSTASH: 'qstash',
+};
+
+// Platform provider names (appDefinition.provider) that map to a built-in queue.
+const PLATFORM_ALIASES = {
+    aws: QUEUE_PROVIDERS.SQS,
+    netlify: QUEUE_PROVIDERS.NETLIFY_BACKGROUND,
+};
+
+/**
+ * Determine the queue provider from the config hierarchy.
+ *
+ * @param {Object} [options]
+ * @param {string} [options.provider]
+ * @param {Object} [options.appDefinition]
+ * @returns {string|undefined}
+ */
+function determineProvider(options = {}) {
+    if (options.provider) {
+        return options.provider;
+    }
+    if (options.appDefinition?.queue?.provider) {
+        return options.appDefinition.queue.provider;
+    }
+    if (process.env.QUEUE_PROVIDER) {
+        return process.env.QUEUE_PROVIDER;
+    }
+    return undefined;
+}
+
+/**
+ * Create a queue provider instance.
+ *
+ * @param {Object} [options]
+ * @param {string} [options.provider] - Queue provider name
+ * @param {Object} [options.appDefinition] - reads `queue.provider`
+ * @param {Object} [options.providerOptions] - passed to the provider constructor
+ * @returns {import('./queue-provider').QueueProvider}
+ */
+function createQueueProvider(options = {}) {
+    const explicit = determineProvider(options);
+    const name = PLATFORM_ALIASES[explicit] || explicit || QUEUE_PROVIDERS.SQS;
+    const providerOptions = options.providerOptions || {};
+
+    switch (name) {
+        case QUEUE_PROVIDERS.SQS: {
+            const { SqsQueueProvider } = require('./providers/sqs-queue-provider');
+            return new SqsQueueProvider(providerOptions);
+        }
+        case QUEUE_PROVIDERS.NETLIFY_BACKGROUND: {
+            const {
+                NetlifyBackgroundProvider,
+            } = require('./providers/netlify-background-provider');
+            return new NetlifyBackgroundProvider(providerOptions);
+        }
+        case QUEUE_PROVIDERS.QSTASH: {
+            const { QStashQueueProvider } = require('./providers/qstash-queue-provider');
+            return new QStashQueueProvider(providerOptions);
+        }
+        default: {
+            const { resolveProvider } = require('../providers/resolve-provider');
+            const provider = resolveProvider(null, { provider: name });
+            if (!provider.QueueProvider) {
+                throw new Error(`Provider '${provider.name || name}' does not export a QueueProvider`);
+            }
+            return new provider.QueueProvider(providerOptions);
+        }
+    }
+}
+
+module.exports = {
+    createQueueProvider,
+    determineProvider,
+    QUEUE_PROVIDERS,
+};

package/queues/queue-provider.js

@@ -0,0 +1,65 @@
+/**
+ * Queue Provider Interface (Port)
+ *
+ * Defines the contract for queue message sending.
+ * All queue adapters must extend this interface.
+ *
+ * Following Frigg's hexagonal architecture pattern:
+ * - Port defines WHAT the service does (contract)
+ * - Adapters implement HOW (AWS SQS, Netlify Background Functions, QStash, etc.)
+ */
+class QueueProvider {
+    /**
+     * Send a single message to a queue
+     *
+     * @param {Object} message - Message payload (will be JSON-serialized)
+     * @param {string} queueId - Queue identifier (URL, name, or endpoint depending on provider)
+     * @returns {Promise<Object>} Provider-specific response
+     */
+    async send(message, queueId) {
+        throw new Error('Method send must be implemented by subclass');
+    }
+
+    /**
+     * Send a batch of messages to a queue
+     *
+     * @param {Object[]} entries - Array of message payloads
+     * @param {string} queueId - Queue identifier
+     * @returns {Promise<Object>} Provider-specific response
+     */
+    async batchSend(entries, queueId) {
+        throw new Error('Method batchSend must be implemented by subclass');
+    }
+
+    /**
+     * Parse an incoming event into an array of message payloads.
+     * Each provider has its own event shape (SQS Records, HTTP body, etc.)
+     *
+     * @param {Object} event - Raw event from the runtime (Lambda event, HTTP request, etc.)
+     * @returns {Object[]} Array of parsed message payloads
+     */
+    parseEvent(event) {
+        throw new Error('Method parseEvent must be implemented by subclass');
+    }
+
+    /**
+     * Prove an incoming event was sent by Frigg before anything is parsed or
+     * dispatched. HTTP-delivered queues (Netlify Background Functions,
+     * QStash) are public URLs, so their adapters check a signature here.
+     *
+     * The default refuses: an adapter that does not know how to verify its
+     * events must not have them run. An adapter whose transport already
+     * authenticates the caller (SQS triggering a Lambda) overrides this, and
+     * must not set `verifiesHttpDelivery`: an HTTP entry point (Netlify's
+     * worker-background) consults only adapters that set it to true, since
+     * a transport-trust answer says nothing about an HTTP caller.
+     *
+     * @param {Object} event - Raw event from the runtime
+     * @returns {Promise<{ ok: boolean, reason?: string, unsigned?: boolean }>}
+     */
+    async verifyEvent(event) {
+        return { ok: false, reason: 'verification_not_implemented' };
+    }
+}
+
+module.exports = { QueueProvider };

package/queues/sqs-queue-client.js

@@ -0,0 +1,81 @@
+/**
+ * SQS Queue Client (Adapter)
+ *
+ * AWS SQS implementation of QueueClientInterface, used by Worker.
+ *
+ * In friggframework/frigg#545 this adapter moved to
+ * @friggframework/provider-aws and Worker required it to be injected. In
+ * this stack the AWS SDK stays a core dependency, so the adapter lives here,
+ * Worker defaults to it, and provider-aws re-exports it. The SDK is
+ * required on first use, not at module load.
+ */
+const { QueueClientInterface } = require('./queue-client-interface');
+
+let sqsModule = null;
+function getSqsModule() {
+    if (!sqsModule) {
+        sqsModule = require('@aws-sdk/client-sqs');
+    }
+    return sqsModule;
+}
+
+/**
+ * Client config #545's adapter used: IS_OFFLINE credentials, AWS_REGION and
+ * AWS_ENDPOINT.
+ */
+function defaultSqsClientConfig() {
+    const config = {};
+    if (process.env.IS_OFFLINE) {
+        config.credentials = {
+            accessKeyId: 'test-aws-key',
+            secretAccessKey: 'test-aws-secret',
+        };
+        config.region = 'us-east-1';
+    }
+    if (!config.region && process.env.AWS_REGION) {
+        config.region = process.env.AWS_REGION;
+    }
+    if (process.env.AWS_ENDPOINT) {
+        config.endpoint = process.env.AWS_ENDPOINT;
+    }
+    return config;
+}
+
+class SqsQueueClient extends QueueClientInterface {
+    /**
+     * @param {Object} [options]
+     * @param {Object} [options.clientConfig] - SQSClient config; defaults to
+     *   defaultSqsClientConfig().
+     */
+    constructor({ clientConfig } = {}) {
+        super();
+        this._clientConfig = clientConfig;
+        this._sqs = null;
+    }
+
+    _client() {
+        if (!this._sqs) {
+            const { SQSClient } = getSqsModule();
+            this._sqs = new SQSClient(this._clientConfig || defaultSqsClientConfig());
+        }
+        return this._sqs;
+    }
+
+    async sendMessage(params) {
+        const { SendMessageCommand } = getSqsModule();
+        return this._client().send(new SendMessageCommand(params));
+    }
+
+    async sendMessageBatch(params) {
+        const { SendMessageBatchCommand } = getSqsModule();
+        return this._client().send(new SendMessageBatchCommand(params));
+    }
+
+    async getQueueUrl(params) {
+        const { GetQueueUrlCommand } = getSqsModule();
+        const data = await this._client().send(new GetQueueUrlCommand(params));
+        return data.QueueUrl;
+    }
+}
+
+module.exports = { SqsQueueClient, defaultSqsClientConfig };

package/types/index.d.ts

@@ -12,4 +12,5 @@
 /// <reference path="./eslint-config/index.d.ts" />
 /// <reference path="./associations/index.d.ts" />
 /// <reference path="./syncs/index.d.ts" />
+/// <reference path="./user/index.d.ts" />
 /// <reference path="./modules/index.d.ts" />

package/types/modules/index.d.ts

@@ -36,13 +36,137 @@ declare module "@friggframework/core" {
     [entityType: string]: EntityRegistration | boolean | undefined;
   }
 
+  /**
+   * One level's setting: a scope, or a default plus the scopes a request may
+   * choose from (ADR-056 §3.1). `global` is never chosen by a tenant request.
+   */
+  export type ScopeSetting =
+    | EntityScope
+    | { default?: EntityScope; allow?: EntityScope[] };
+
+  /**
+   * `appDefinition.ownership` (ADR-056 §3, §3.6). Resolution order for a new
+   * connection: request, binding, integration, entity type (`entities[name].scope`),
+   * this `scope`, then `organization` for an organization-primary app and
+   * `individual` otherwise.
+   */
+  export interface AppOwnership {
+    scope?: ScopeSetting;
+    /**
+     * `'organization'` (default): an individual entity belongs to the organization
+     * it was connected in. `'all'`: one connection per person across every
+     * organization, stored with no `organizationId`.
+     */
+    individualAcross?: "organization" | "all";
+  }
+
+  /** `Definition.ownership` on an integration (ADR-056 §3.1, §3.3). */
+  export interface IntegrationOwnership {
+    /** Scope every binding of this integration accepts unless it sets its own. */
+    scope?: ScopeSetting;
+    /** `'derive'` (default): organization when every entity it uses is organization-scoped. */
+    owner?: "derive" | "individual" | "organization";
+  }
+
+  /** One operation a module or the app lets the entity proxy forward (ADR-052). */
+  export interface ProxyAllowRule {
+    method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE" | "*";
+    /** Relative to the module's base URL. `:param` is one segment; a trailing `/**` is a subtree. */
+    path: string;
+  }
+
+  /** `appDefinition.managementApi.proxy`: the entity proxy, POST /api/v2/entities/:id/proxy (ADR-052). */
+  export interface ManagementApiProxyConfig {
+    /** Mount the route. Default false. */
+    enable?: boolean;
+    /** Upstream timeout in ms; can only be lowered from 25000. */
+    timeoutMs?: number;
+    /** Largest request body in bytes; default 1 MiB, at most 10 MiB. */
+    maxRequestBytes?: number;
+    /** Largest response body in bytes; can only be lowered from 5 MiB. */
+    maxResponseBytes?: number;
+    /**
+     * Entity scopes the proxy accepts (ADR-056 §3.5). Default `['individual']`.
+     * Add `'organization'` to let a member with use access proxy through the
+     * organization's shared credential. `global` is never accepted. An unknown,
+     * empty or repeated value throws ManagementApiConfigError at load.
+     */
+    scopes?: Array<Exclude<EntityScope, "global">>;
+    /** Per-module allow-list override; `'module'` uses the module's own list. */
+    modules?: Record<string, { allow: "module" | ProxyAllowRule[] }>;
+  }
+
+  /** `appDefinition.managementApi` (ADR-052, ADR-053). */
+  export interface ManagementApiConfig {
+    /** Serve the deprecated v1 routes. Default true. */
+    v1?: boolean;
+    proxy?: ManagementApiProxyConfig;
+  }
+
   export interface AppDefinition {
     integrations: any[];
     /** App-level entity type registry (ADR-059). */
     entities?: AppDefinitionEntities;
+    /** Who owns what a person connects (ADR-056). */
+    ownership?: AppOwnership;
+    /** Management API versions and the entity proxy (ADR-052, ADR-053, ADR-056 §3.5). */
+    managementApi?: ManagementApiConfig;
     [key: string]: unknown;
   }
 
+  /** Whose a record is and what the caller may do with it (ADR-056 §3.4). */
+  export interface RecordTenancy {
+    scope: Exclude<EntityScope, "global">;
+    owner: { type: Exclude<EntityScope, "global">; id: string };
+    /** Null for an individual entity connected outside an organization, or under `individualAcross: 'all'`. */
+    organizationId: string | null;
+    /** `manage`: create, reauthorize, delete. `use`: bind it, proxy through it. `view`: metadata only. */
+    access: "manage" | "use" | "view";
+  }
+
+  /** Which scope a connection gets, and from which level of the order (ADR-056 §3.1). */
+  export interface ResolvedScope {
+    scope: EntityScope;
+    /** Where `scope` came from. `request` when the request chose within the allowed list. */
+    source: "request" | "binding" | "integration" | "entityType" | "app" | "default";
+    /** The level that decided what a request may choose from. */
+    decidedBy: "binding" | "integration" | "entityType" | "app" | "default";
+    allow: EntityScope[];
+  }
+
+  /**
+   * First match wins, each level overriding the ones below it. A request may
+   * choose only from the deciding level's `allow`; `global` never comes from a
+   * tenant request. Throws a Boom 400/403 for a request scope that is not allowed.
+   */
+  export function resolveScope(levels: {
+    request?: EntityScope;
+    binding?: ScopeSetting;
+    integration?: ScopeSetting;
+    entityType?: ScopeSetting;
+    app?: ScopeSetting;
+    primary?: "individual" | "organization";
+  }): ResolvedScope;
+
+  /** Every binding of every integration with its resolved scope (for tooling that wants to show the chain). */
+  export function listBindingScopes(
+    appDefinition: Pick<AppDefinition, "integrations" | "ownership">,
+    entityTypeRegistry: EntityTypeRegistry,
+    primary?: "individual" | "organization"
+  ): Array<{
+    integration: string;
+    binding: string;
+    moduleName: string | null;
+    scope: EntityScope;
+    source: ResolvedScope["source"];
+    owner: "derive" | "individual" | "organization";
+  }>;
+
+  /** Invalid ownership or scope setting, thrown at app-definition load. `code` is always `OWNERSHIP_CONFIG_INVALID`. */
+  export class OwnershipConfigError extends Error {
+    code: "OWNERSHIP_CONFIG_INVALID";
+  }
+
   /**
    * Builds the registry from `entities` plus the modules integrations bind.
    * Throws EntityRegistryError on an invalid registry.
@@ -51,6 +175,21 @@ declare module "@friggframework/core" {
     appDefinition?: Pick<AppDefinition, "entities" | "integrations">
   ): EntityTypeRegistry;
 
+  /** Invalid `managementApi` setting (today: `proxy.scopes`), thrown at app-definition load. */
+  export class ManagementApiConfigError extends Error {
+    code: "MANAGEMENT_API_CONFIG_INVALID";
+  }
+
+  /**
+   * @deprecated ADR-059. Use `getEntityTypeRegistry(appDefinition)` and read
+   * each entry's `definition`. Returns the registry's definitions for these
+   * integrations (plus registry-only types when `entities` is passed).
+   */
+  export function getModulesDefinitionFromIntegrationClasses(
+    integrationClasses: any[],
+    entities?: AppDefinitionEntities
+  ): any[];
+
   /** Invalid `entities` registry. `code` is always `ENTITY_REGISTRY_INVALID`. */
   export class EntityRegistryError extends Error {
     code: "ENTITY_REGISTRY_INVALID";

package/types/user/index.d.ts

@@ -0,0 +1,134 @@
+declare module "@friggframework/core/user" {
+  export type AdopterJwtAlgorithm =
+    | "ES256"
+    | "ES384"
+    | "RS256"
+    | "RS384"
+    | "RS512"
+    | "HS256"
+    | "HS384"
+    | "HS512";
+
+  /**
+   * Verification of tokens issued by the adopter's identity system
+   * (`authModes.adopterJwt`, ADR-056 §2). Set exactly one of `jwksUri` or `secret`.
+   */
+  export interface AdopterJwtConfig {
+    /** https URL of the issuer's JWKS (http only for localhost, 127.0.0.0/8, ::1). */
+    jwksUri?: string;
+    /** Shared HMAC secret for HS* tokens. */
+    secret?: string;
+    /** Required `iss`. With `jwksUri`, a startup warning is logged when unset. */
+    issuer?: string;
+    /** Accepted `aud`. Required with `jwksUri`. */
+    audience?: string | string[];
+    /** Allow-list. Default ES256 and RS256 with `jwksUri`, HS256 with `secret`. */
+    algorithms?: AdopterJwtAlgorithm[];
+    /** @deprecated Use `algorithms`. Setting both is an error. */
+    algorithm?: AdopterJwtAlgorithm;
+    /** Skew allowed on `exp` and `nbf`. Default 30. */
+    clockToleranceSec?: number;
+    /** Default `sub`. */
+    userIdClaim?: string;
+    /** Default `org_id`. */
+    orgIdClaim?: string;
+    /** Default `org_role`. Exposed as `User#getOrgRole()`; stored on a new membership. */
+    roleClaim?: string;
+  }
+
+  export interface UserAuthModes {
+    friggToken?: boolean;
+    sharedSecret?: boolean;
+    adopterJwt?: boolean;
+  }
+
+  /** The `user` block of the app definition. */
+  export interface UserConfig {
+    usePassword?: boolean;
+    primary?: "individual" | "organization";
+    individualUserRequired?: boolean;
+    organizationUserRequired?: boolean;
+    /**
+     * With `x-frigg` headers, refuse (400) to make a person a member of an
+     * organization that already existed: anyone not already a member, a
+     * brand-new `appUserId` included, is rejected. Naming an organization the
+     * request itself creates is still allowed. Default false (a non-member is
+     * added).
+     */
+    strictMembership?: boolean;
+    /**
+     * @deprecated Alias of `strictMembership`, with the same new meaning (it
+     * used to reject a mismatched individual/organization pair). Logs a warning
+     * at startup. `strictMembership` wins when both are set.
+     */
+    strictUserValidation?: boolean;
+    /**
+     * Roles that may manage organization-level things (ADR-056 §3). Default
+     * `['ADMIN']`. The role is the adopter token's role claim, else the stored
+     * membership `orgRole`, else `MEMBER` (never admin). A shared-secret
+     * (`x-frigg` header) caller needs no role, nor does a Frigg bearer token
+     * unless `orgAdminGateBearerTokens`. Compared case-insensitively.
+     * Validated at load.
+     */
+    orgAdminRoles?: string[];
+    /**
+     * Judge Frigg bearer-token callers by role like adopter-token callers.
+     * Default false: they keep their behaviour from before organization roles.
+     */
+    orgAdminGateBearerTokens?: boolean;
+    authModes?: UserAuthModes;
+    jwtConfig?: AdopterJwtConfig;
+  }
+
+  /**
+   * One person's membership of one organization (ADR-056 §3.6). `implicit` is
+   * true when it is only the legacy `IndividualUser.organizationId` pointer.
+   */
+  export interface OrganizationMembership {
+    id: string | null;
+    individualUserId: string;
+    organizationUserId: string;
+    /** Defaults to `MEMBER`. */
+    orgRole: string;
+    createdAt?: Date;
+    implicit: boolean;
+  }
+
+  export interface OrganizationMembershipRepository {
+    /** The stored row or null: the legacy `organizationId` pointer is not read here. */
+    findMembership(
+      individualUserId: string,
+      organizationUserId: string
+    ): Promise<OrganizationMembership | null>;
+    /** Idempotent: adds when absent, never changes an existing membership. */
+    addMembership(
+      individualUserId: string,
+      organizationUserId: string,
+      options?: { orgRole?: string | null }
+    ): Promise<OrganizationMembership>;
+    /** Stored rows only, oldest first; legacy-pointer people are not here. */
+    listMembershipsForOrganization(
+      organizationUserId: string
+    ): Promise<OrganizationMembership[]>;
+  }
+
+  export function createOrganizationMembershipRepository(): OrganizationMembershipRepository;
+
+  export class User {
+    /** The primary user's id; under `primary: 'organization'` the ACTIVE organization. */
+    getId(): string | undefined;
+    /** The organization this request acts in (token or `x-frigg-apporgid`), or null. */
+    getActiveOrganizationId(): string | null;
+    getAppUserId(): string | null;
+    getAppOrgId(): string | null;
+    getIndividualUser(): any;
+    getOrganizationUser(): any;
+    getPrimaryUser(): any;
+    /** The organization role from the adopter token for this request, or null. */
+    getOrgRole(): string | null;
+    setOrgRole(orgRole: string | null): void;
+    /** The stored `orgRole` of the membership of the active organization, or null. Used when the token carries no role. */
+    getMembershipRole(): string | null;
+    setMembershipRole(membershipRole: string | null): void;
+  }
+}