@friggframework/schemas 2.0.0--canary.669.5f3833b.0 → 2.0.0--canary.671.dc3e89f.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@friggframework/schemas",
-  "version": "2.0.0--canary.669.5f3833b.0",
+  "version": "2.0.0--canary.671.dc3e89f.0",
   "description": "Canonical JSON Schema definitions for Frigg Framework",
   "main": "index.js",
   "author": "",
@@ -41,5 +41,5 @@
     "middleware/",
     "index.js"
   ],
-  "gitHead": "5f3833bb5b4ce23d3d2abb5bb6e9453edf73e2d3"
+  "gitHead": "dc3e89fb7d431925d91d652e1e55801da77e2e45"
 }

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": {
@@ -147,7 +147,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 +161,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 +201,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 +223,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

@@ -643,6 +643,101 @@
       },
       "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",