@friggframework/core 2.0.0--canary.686.3e27a92.0 → 2.0.0--canary.663.8de669c.0

package/queues/queue-provider-factory.js

@@ -1,101 +0,0 @@
-/**
- * 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

@@ -1,65 +0,0 @@
-/**
- * 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

@@ -1,81 +0,0 @@
-/**
- * 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/modules/index.d.ts

@@ -1,197 +0,0 @@
-declare module "@friggframework/core" {
-  /** Where an entity type comes from: the app's `entities` map or an integration binding it. */
-  export type EntityTypeSource =
-    | { kind: "app" }
-    | { kind: "integration"; name: string };
-
-  export type EntityScope = "individual" | "organization" | "global";
-
-  /** App-level settings carried from the `entities` entry; empty for an inferred-only type. */
-  export interface EntityTypeSettings {
-    scope?: EntityScope | { default?: EntityScope; allow?: EntityScope[] };
-    proxy?: Record<string, unknown>;
-    display?: Record<string, unknown>;
-  }
-
-  export interface EntityTypeEntry {
-    /** The API module definition. */
-    definition: any;
-    /** Frozen. `{ kind: 'app' }` first when registered, then each binding integration. */
-    sources: readonly EntityTypeSource[];
-    /** Frozen. */
-    settings: Readonly<EntityTypeSettings>;
-  }
-
-  /** Entity type name (the definition's moduleName) to its entry. */
-  export type EntityTypeRegistry = Map<string, EntityTypeEntry>;
-
-  /** One `appDefinition.entities` entry. The key must equal the definition's moduleName (and getName() when defined). */
-  export interface EntityRegistration extends EntityTypeSettings {
-    definition: any;
-  }
-
-  export interface AppDefinitionEntities {
-    /** false turns inference off: every module an integration binds must be registered. Default true. */
-    $infer?: boolean;
-    [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.
-   */
-  export function getEntityTypeRegistry(
-    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

@@ -1,134 +0,0 @@
-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;
-  }
-}