@friggframework/schemas 2.0.0--canary.704.79d9a63.0 → 2.0.0--canary.680.daae24e.0

package/README.md

@@ -185,7 +185,7 @@ Defines the structure for Serverless Framework configuration used in AWS deploym
 **Example:**
 ```javascript
 const serverlessConfig = {
-    frameworkVersion: "^4.4.0",
+    frameworkVersion: ">=3.17.0",
     service: "frigg-backend",
     provider: {
         name: "aws",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@friggframework/schemas",
-  "version": "2.0.0--canary.704.79d9a63.0",
+  "version": "2.0.0--canary.680.daae24e.0",
   "description": "Canonical JSON Schema definitions for Frigg Framework",
   "main": "index.js",
   "author": "",
@@ -41,5 +41,5 @@
     "middleware/",
     "index.js"
   ],
-  "gitHead": "79d9a635432643710e9fb815cf16453d01f7e12c"
+  "gitHead": "daae24ec9d6b03c59759b6b42f6f99369b683981"
 }

package/schemas/api-authorization.schema.json

@@ -6,13 +6,13 @@
   "definitions": {
     "authorizationRequirements": {
       "type": "object",
-      "description": "Authorization requirements response from GET /api/authorize",
+      "description": "Authorization requirements response from GET /api/v2/authorize (GET /api/authorize in v1 returns the module requirements unwrapped)",
       "required": ["type", "step", "totalSteps", "isMultiStep"],
       "properties": {
         "type": {
           "type": "string",
-          "enum": ["oauth2", "form", "api-key", "basic"],
-          "description": "Type of authentication required"
+          "description": "Type of authentication required: oauth2, form, api-key, basic, or a module-defined step type (e.g. email, otp)",
+          "examples": ["oauth2", "form", "api-key", "basic", "otp"]
         },
         "step": {
           "type": "integer",
@@ -112,13 +112,13 @@
     },
     "getEntityTypeRequirementsResponse": {
       "type": "object",
-      "description": "Authorization requirements response from GET /api/entities/types/:typeName/requirements",
+      "description": "Authorization requirements response from GET /api/v2/entities/types/:entityType/requirements",
       "required": ["type", "step", "totalSteps", "isMultiStep"],
       "properties": {
         "type": {
           "type": "string",
-          "enum": ["oauth2", "form", "api-key", "basic"],
-          "description": "Type of authentication required"
+          "description": "Type of authentication required: oauth2, form, api-key, basic, or a module-defined step type (e.g. email, otp)",
+          "examples": ["oauth2", "form", "api-key", "basic", "otp"]
         },
         "step": {
           "type": "integer",
@@ -151,7 +151,7 @@
     },
     "authorizationRequest": {
       "type": "object",
-      "description": "Authorization request to POST /api/authorize",
+      "description": "Authorization request to POST /api/v2/authorize (and v1 POST /api/authorize)",
       "required": ["entityType"],
       "properties": {
         "entityType": {
@@ -238,6 +238,40 @@
         }
       }
     },
+    "authorizeComplete": {
+      "type": "object",
+      "description": "POST /api/v2/authorize (or /api/v2/credentials/:credentialId/reauthorize) when the flow is complete. The credential is masked.",
+      "required": ["status", "entity", "credential"],
+      "properties": {
+        "status": { "const": "complete" },
+        "entity": { "type": "object", "description": "api-entities#/definitions/entity" },
+        "credential": { "type": "object", "description": "api-credentials#/definitions/credential, masked" },
+        "previousCredentialId": {
+          "type": "string",
+          "description": "Re-authorization only: set when the provider account changed and a new credential was stored"
+        }
+      }
+    },
+    "authorizePending": {
+      "type": "object",
+      "description": "POST /api/v2/authorize when another step is needed",
+      "required": ["status", "step", "totalSteps", "sessionId", "requirements"],
+      "properties": {
+        "status": { "const": "pending" },
+        "step": { "type": "integer", "minimum": 2 },
+        "totalSteps": { "type": "integer", "minimum": 2 },
+        "sessionId": { "type": "string" },
+        "requirements": { "$ref": "#/definitions/authorizationRequirements" },
+        "message": { "type": "string" }
+      }
+    },
+    "authorizeV2Response": {
+      "description": "Response from POST /api/v2/authorize and POST /api/v2/credentials/:credentialId/reauthorize",
+      "oneOf": [
+        { "$ref": "#/definitions/authorizeComplete" },
+        { "$ref": "#/definitions/authorizePending" }
+      ]
+    },
     "authorizationSession": {
       "type": "object",
       "description": "Authorization session stored in database",

package/schemas/api-credentials.schema.json

@@ -48,7 +48,7 @@
     },
     "listCredentialsResponse": {
       "type": "object",
-      "description": "Response from GET /api/credentials - returns list of credentials for the authenticated user",
+      "description": "Response from GET /api/v2/credentials - returns list of credentials for the authenticated user",
       "required": ["credentials"],
       "properties": {
         "credentials": {
@@ -61,7 +61,7 @@
       }
     },
     "getCredentialResponse": {
-      "description": "Response from GET /api/credentials/:id - returns a single credential",
+      "description": "Response from GET /api/v2/credentials/:credentialId - returns a single credential",
       "allOf": [
         {
           "$ref": "#/definitions/credential"
@@ -70,7 +70,7 @@
     },
     "deleteCredentialResponse": {
       "type": "object",
-      "description": "Response from DELETE /api/credentials/:id",
+      "description": "Legacy delete result. DELETE /api/v2/credentials/:credentialId answers 204 No Content.",
       "required": ["success"],
       "properties": {
         "success": {
@@ -85,7 +85,7 @@
     },
     "reauthorizeCredentialRequest": {
       "type": "object",
-      "description": "Request to POST /api/credentials/:id/reauthorize - refresh or update credential authentication",
+      "description": "Request to POST /api/v2/credentials/:credentialId/reauthorize - refresh or update credential authentication",
       "required": ["data"],
       "properties": {
         "data": {
@@ -107,7 +107,7 @@
     },
     "reauthorizeCredentialResponse": {
       "type": "object",
-      "description": "Response from POST /api/credentials/:id/reauthorize - either success or next step",
+      "description": "Legacy re-authorization result. POST /api/v2/credentials/:credentialId/reauthorize answers api-authorization#/definitions/authorizeV2Response.",
       "oneOf": [
         {
           "$ref": "#/definitions/reauthorizeCredentialSuccess"

package/schemas/api-entities.schema.json

@@ -51,7 +51,7 @@
     },
     "listEntitiesResponse": {
       "type": "object",
-      "description": "Response from GET /api/entities",
+      "description": "Response from GET /api/v2/entities",
       "required": ["entities"],
       "properties": {
         "entities": {
@@ -65,7 +65,7 @@
     },
     "createEntityRequest": {
       "type": "object",
-      "description": "Request to POST /api/entities",
+      "description": "Request to POST /api/entities (v1 POST /api/entity). Not served by v2: POST /api/v2/authorize creates the entity.",
       "required": ["entityType", "data"],
       "properties": {
         "entityType": {
@@ -88,7 +88,7 @@
     },
     "createEntityResponse": {
       "type": "object",
-      "description": "Response from POST /api/entities",
+      "description": "Response from POST /api/entities (v1 POST /api/entity). Not served by v2.",
       "required": ["entity_id", "credential_id", "type"],
       "properties": {
         "entity_id": {
@@ -122,6 +122,11 @@
           "type": "string",
           "description": "Description of the entity type"
         },
+        "usedBy": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Names of the integrations that bind this entity type; empty for a type registered only in appDefinition.entities"
+        },
         "authType": {
           "type": "string",
           "enum": ["oauth2", "form", "api-key", "basic"],
@@ -147,7 +152,7 @@
     },
     "listEntityTypesResponse": {
       "type": "object",
-      "description": "Response from GET /api/entities/types",
+      "description": "Response from GET /api/v2/entities/types",
       "required": ["types"],
       "properties": {
         "types": {
@@ -161,7 +166,7 @@
     },
     "getEntityTypeResponse": {
       "type": "object",
-      "description": "Response from GET /api/entities/types/:typeName",
+      "description": "Response from GET /api/v2/entities/types/:entityType",
       "required": ["type", "name"],
       "properties": {
         "type": {
@@ -201,7 +206,7 @@
     },
     "reauthorizeEntityRequest": {
       "type": "object",
-      "description": "Request to POST /api/entities/:id/reauthorize",
+      "description": "Request to re-authorize an entity. Not served in 2.0.1: use POST /api/v2/credentials/:credentialId/reauthorize.",
       "required": ["data"],
       "properties": {
         "data": {
@@ -223,7 +228,7 @@
     },
     "reauthorizeEntityResponse": {
       "type": "object",
-      "description": "Response from POST /api/entities/:id/reauthorize (success or next step)",
+      "description": "Entity re-authorization result. Not served in 2.0.1: POST /api/v2/credentials/:credentialId/reauthorize answers api-authorization#/definitions/authorizeV2Response.",
       "oneOf": [
         {
           "$ref": "#/definitions/reauthorizeEntitySuccess"

package/schemas/api-module-definition.schema.json

@@ -94,6 +94,40 @@
       },
       "additionalProperties": false
     },
+    "proxy": {
+      "type": "object",
+      "description": "Opt in to the Management API entity proxy (ADR-052). Without allow, nothing can be proxied.",
+      "properties": {
+        "allow": {
+          "type": "array",
+          "description": "Operations that may be proxied. :param matches one segment; a trailing /** matches a subtree. Wildcards (method * or path /**) are ignored here and only accepted in the app definition.",
+          "items": {
+            "type": "object",
+            "required": ["method", "path"],
+            "properties": {
+              "method": { "type": "string", "enum": ["GET", "POST", "PUT", "PATCH", "DELETE"] },
+              "path": { "type": "string", "pattern": "^/" }
+            },
+            "additionalProperties": false
+          }
+        },
+        "headers": {
+          "type": "array",
+          "description": "Provider-specific request headers callers may send, in addition to accept, content-type, accept-language, if-match and if-none-match",
+          "items": { "type": "string" }
+        },
+        "baseUrl": {
+          "description": "Proxy base URL (https). A string, or a function of the Api instance for tenant hosts. Defaults to the Api's baseUrl.",
+          "type": ["string", "object"]
+        },
+        "binary": {
+          "type": "boolean",
+          "default": false,
+          "description": "Return binary upstream bodies base64-encoded instead of refusing them (415)"
+        }
+      },
+      "additionalProperties": false
+    },
     "env": {
       "type": "object",
       "description": "Environment variable configuration",

package/schemas/api-proxy.schema.json

@@ -6,7 +6,7 @@
   "definitions": {
     "proxyRequest": {
       "type": "object",
-      "description": "Proxy request to POST /api/entities/:id/proxy or POST /api/credentials/:id/proxy",
+      "description": "Proxy request to POST /api/v2/entities/:entityId/proxy (ADR-052). Off unless the app sets managementApi.proxy.enable, and only for paths the module (or the app definition) allow-lists.",
       "required": ["method", "path"],
       "properties": {
         "method": {
@@ -16,7 +16,7 @@
         },
         "path": {
           "type": "string",
-          "description": "API path to call on the upstream service (e.g., '/v3/contacts' or '/api/users')",
+          "description": "Path relative to the module's base URL (e.g. '/v3/contacts'). Must start with a single /. Rejected: //, backslashes, ? and # (use query), . and .. segments, encoded separators (%2f, %5c), double encoding, control and whitespace characters other than %20. The host always comes from the module.",
           "pattern": "^/",
           "minLength": 1
         },
@@ -37,7 +37,7 @@
         },
         "headers": {
           "type": "object",
-          "description": "Additional headers to include in the upstream request (authorization headers are added automatically)",
+          "description": "Request headers. Only accept, content-type, accept-language, if-match, if-none-match and headers the module lists in proxy.headers are forwarded; others are dropped. Authorization, Proxy-Authorization, Cookie, Host, Forwarded, X-Forwarded-*, X-Real-IP, X-API-Key and the module's own auth header are refused (400). Auth headers come only from the module.",
           "additionalProperties": { "type": "string" }
         },
         "body": {
@@ -84,19 +84,23 @@
     },
     "proxyResponse": {
       "type": "object",
-      "description": "Successful proxy response with data from upstream API",
+      "description": "Upstream answer relayed by the proxy. The HTTP status of the Frigg response equals `status`; `success` is false for upstream 4xx.",
       "required": ["success", "status", "data"],
       "properties": {
         "success": {
           "type": "boolean",
-          "const": true,
-          "description": "Indicates successful proxy operation"
+          "description": "True when the upstream status is below 400"
         },
         "status": {
           "type": "integer",
           "minimum": 200,
-          "maximum": 299,
-          "description": "HTTP status code from the upstream API response"
+          "maximum": 499,
+          "description": "HTTP status code from the upstream API response (5xx, 401 and 429 are reported as proxy errors)"
+        },
+        "dataEncoding": {
+          "type": "string",
+          "enum": ["base64"],
+          "description": "Present when data is a base64-encoded binary body (only for modules with proxy.binary: true)"
         },
         "headers": {
           "type": "object",
@@ -171,16 +175,25 @@
               "type": "string",
               "description": "Error code identifying the type of failure",
               "enum": [
-                "INVALID_AUTH",
-                "EXPIRED_TOKEN",
+                "INVALID_PROXY_REQUEST",
+                "PROXY_NOT_ALLOWED",
+                "PROXY_NOT_CONFIGURED",
+                "PAYLOAD_TOO_LARGE",
+                "UNSUPPORTED_MEDIA_TYPE",
+                "RESPONSE_TOO_LARGE",
+                "INVALID_CREDENTIALS",
+                "RATE_LIMITED",
                 "UPSTREAM_ERROR",
                 "TIMEOUT",
                 "NETWORK_ERROR",
-                "RATE_LIMITED",
-                "INVALID_REQUEST",
+                "ENTITY_NOT_FOUND",
                 "NOT_FOUND",
+                "UNAUTHORIZED",
+                "VALIDATION_ERROR",
+                "INVALID_AUTH",
+                "EXPIRED_TOKEN",
+                "INVALID_REQUEST",
                 "PERMISSION_DENIED",
-                "INVALID_CREDENTIALS",
                 "SERVICE_UNAVAILABLE"
               ]
             },

package/schemas/app-definition.schema.json

@@ -75,39 +75,6 @@
       },
       "default": []
     },
-    "adminScripts": {
-      "type": "array",
-      "description": "Admin script classes (extending AdminScriptBase from @friggframework/admin-scripts) served under /admin/scripts",
-      "items": {
-        "description": "Admin script class"
-      },
-      "default": []
-    },
-    "reports": {
-      "type": "array",
-      "description": "Report classes served by the admin report runner",
-      "items": {
-        "description": "Report class"
-      },
-      "default": []
-    },
-    "admin": {
-      "type": "object",
-      "description": "Admin script and report runner options",
-      "properties": {
-        "enableScheduling": {
-          "type": "boolean",
-          "description": "Provision the EventBridge Scheduler group and role so admin scripts and reports can run on a schedule",
-          "default": false
-        },
-        "includeBuiltinReports": {
-          "type": "boolean",
-          "description": "Serve the built-in reports alongside the app's own reports",
-          "default": false
-        }
-      },
-      "additionalProperties": false
-    },
     "user": {
       "type": "object",
       "description": "User management and authentication configuration",
@@ -344,8 +311,8 @@
       "properties": {
         "fieldLevelEncryptionMethod": {
           "type": "string",
-          "description": "Method for field-level encryption",
-          "enum": ["kms", "aes"],
+          "description": "Method for field-level encryption. 'kms' creates or discovers a KMS key and sets KMS_KEY_ARN; 'aes' expects AES_KEY_ID and AES_KEY in the Lambda environment; 'none' sets FRIGG_ENCRYPTION_DISABLED=true and stores sensitive fields in plaintext. A deployed stage with no key and no 'none' opt-out refuses to start.",
+          "enum": ["kms", "aes", "none"],
           "default": "aes"
         },
         "createResourceIfNoneFound": {
@@ -676,6 +643,151 @@
       },
       "additionalProperties": false
     },
+    "entities": {
+      "type": "object",
+      "description": "App-level entity type registry (ADR-059). Keyed by entity type name; each key must equal its definition's moduleName / getName(). Registered types can be connected without any integration. Entity types bound by declared integrations are inferred and merged unless $infer is false.",
+      "properties": {
+        "$infer": {
+          "type": "boolean",
+          "default": true,
+          "description": "false turns inference off: every module an integration binds must then be registered here, or the app fails to load."
+        }
+      },
+      "additionalProperties": {
+        "type": "object",
+        "description": "One entity type: its module definition plus app-level settings.",
+        "required": ["definition"],
+        "properties": {
+          "definition": {
+            "type": "object",
+            "description": "The API module definition (the object an integration binds as modules.<key>.definition)."
+          },
+          "scope": {
+            "description": "Who owns entities of this type (ADR-056): one scope, or a default plus the scopes callers may choose.",
+            "oneOf": [
+              { "type": "string", "enum": ["individual", "organization", "global"] },
+              {
+                "type": "object",
+                "properties": {
+                  "default": { "type": "string", "enum": ["individual", "organization", "global"] },
+                  "allow": {
+                    "type": "array",
+                    "items": { "type": "string", "enum": ["individual", "organization", "global"] },
+                    "minItems": 1,
+                    "uniqueItems": true
+                  }
+                },
+                "additionalProperties": false
+              }
+            ]
+          },
+          "proxy": {
+            "type": "object",
+            "description": "Per-type entity proxy allow-list override (ADR-052)."
+          },
+          "display": {
+            "type": "object",
+            "description": "Label, icon and description shown by UIs and GET /api/v2/entity-types."
+          }
+        },
+        "additionalProperties": false
+      }
+    },
+    "managementApi": {
+      "type": "object",
+      "description": "Management API settings (ADR-053 versioning, ADR-052 entity proxy).",
+      "properties": {
+        "v1": {
+          "type": "boolean",
+          "default": true,
+          "description": "Serve the deprecated v1 routes (unprefixed /api/*). false removes them from the router and from the generated API Gateway routes."
+        },
+        "proxy": {
+          "type": "object",
+          "description": "Entity proxy, POST /api/v2/entities/:id/proxy (ADR-052). Off by default.",
+          "properties": {
+            "enable": {
+              "type": "boolean",
+              "default": false,
+              "description": "Mount the entity proxy route and advertise the entityProxy capability."
+            },
+            "timeoutMs": {
+              "type": "integer",
+              "minimum": 1,
+              "maximum": 25000,
+              "default": 25000,
+              "description": "Upstream timeout for one proxied call, in milliseconds (can only be lowered)."
+            },
+            "maxRequestBytes": {
+              "type": "integer",
+              "minimum": 1,
+              "maximum": 10485760,
+              "default": 1048576,
+              "description": "Largest proxied request body, in bytes."
+            },
+            "maxResponseBytes": {
+              "type": "integer",
+              "minimum": 1,
+              "maximum": 5242880,
+              "default": 5242880,
+              "description": "Largest proxied response body, in bytes (can only be lowered)."
+            },
+            "modules": {
+              "type": "object",
+              "description": "Per-module allow-list override, keyed by module name. 'module' uses the module's own proxy.allow list.",
+              "additionalProperties": {
+                "type": "object",
+                "properties": {
+                  "allow": {
+                    "oneOf": [
+                      {
+                        "type": "string",
+                        "enum": [
+                          "module"
+                        ]
+                      },
+                      {
+                        "type": "array",
+                        "items": {
+                          "type": "object",
+                          "required": [
+                            "method",
+                            "path"
+                          ],
+                          "properties": {
+                            "method": {
+                              "type": "string",
+                              "enum": [
+                                "GET",
+                                "POST",
+                                "PUT",
+                                "PATCH",
+                                "DELETE",
+                                "*"
+                              ],
+                              "description": "HTTP method, or * for any (app definition only; frigg validate warns)"
+                            },
+                            "path": {
+                              "type": "string",
+                              "pattern": "^/",
+                              "description": "Path pattern relative to the module's base URL. `:param` matches one segment; a trailing `/**` matches a subtree."
+                            }
+                          },
+                          "additionalProperties": false
+                        }
+                      }
+                    ]
+                  }
+                },
+                "additionalProperties": false
+              }
+            }
+          },
+          "additionalProperties": false
+        }
+      },
+      "additionalProperties": false
+    },
     "custom": {
       "type": "object",
       "description": "Custom application-specific configuration",

package/schemas/serverless-config.schema.json

@@ -8,9 +8,9 @@
   "properties": {
     "frameworkVersion": {
       "type": "string",
-      "description": "osls (Serverless Framework v3-compatible) version constraint. Frigg emits ^4.4.0 (ADR-050).",
-      "pattern": "^[><=^~]*\\d+(\\.\\d+){0,2}$",
-      "examples": ["^4.4.0", ">=4.4.0", "4.4.0"]
+      "description": "Serverless Framework version constraint",
+      "pattern": "^[><=]*\\d+\\.\\d+\\.\\d+$",
+      "examples": [">=3.17.0", "3.38.0"]
     },
     "service": {
       "type": "string",
@@ -353,7 +353,7 @@
   "additionalProperties": false,
   "examples": [
     {
-      "frameworkVersion": "^4.4.0",
+      "frameworkVersion": ">=3.17.0",
       "service": "frigg-backend",
       "provider": {
         "name": "aws",