{
  "schema": "aaes/capability-pack/1",
  "provider": "box",
  "version": "1.0.0",
  "description": "Box API on the customer's enterprise: list folder items, read file metadata, delete files and folders, and create shared links on files.",
  "notes": "The endpoint host 'box-api.invalid' is a reserved non-production placeholder (an RFC 2606 reserved TLD): substitute the real Box API host before enabling, in every endpoint, in the resource locator and in every egress allowlist entry — the reviewed documentation names the API host https://api.box.com with the /2.0 path prefix, and the OAuth2 token endpoint shares that host, so one placeholder covers both. The allowlist matches exactly, so endpoints and allowlist must be substituted together, and substitution is a required deployment step. FOLDER_ID and FILE_ID in the endpoint paths are placeholders the deployment binds before enabling; the reviewed documentation notes the root folder of a Box account is always ID 0.\n\nDocumented exclusions: this pack does not register collaborations (inviting a collaborator grants another party access to content — a share effect needing its own review), file upload, new-version upload, file copy, folder creation and watermarking, trash operations including permanent purge of trashed items (unrecoverable), retention policies and legal holds, user and enterprise administration, and the As-User impersonation header the retrieved OAuth2 guide mentions. The shared-link capability is registered only for files; creating shared links on folders is a deliberate exclusion — a folder link exposes everything the folder contains now and later, a larger and less reviewable blast radius.\n\nApproval classification: shared-link creation declares update and share at the minimum R3 tier — the reviewed documentation shows access 'open' yields a public URL with a direct download_url, and disclosed information cannot be made private again once the other party has it. Endpoint scope: the shared-link capability is the general Update File PUT, so the exclusions above do not cover file moves or file metadata writes — both are reachable through that registered capability's unrestricted body (a parent change moves the file; name, description, tags and lock are writable), and policy, not intent, must constrain the access level and the other writable fields.\n\nFolder deletion registers delete at R3 and the reviewed documentation shows the recursive query parameter deletes a non-empty folder and all of its content — high blast radius; the deployment should require per-request human approval for any recursive call.",
  "credential": {
    "secret_ref_id": "secret-ref-box-oauth-token",
    "custody": "customer_vault",
    "inject": "header",
    "inject_name": "Authorization",
    "note": "An OAuth 2.0 access token for the customer's Box enterprise, held in the client's own secret manager. The stored material must be the complete Authorization header value: the scheme 'Bearer', one separating space, then the access token — 'Bearer <token>'. The OAuth2 refresh flow is according to the reviewed guide, an external deployment process creates a Platform App in the Box Developer Console (OAuth 2.0 authentication method), copies its client_id and client_secret, drives the authorization redirect and user-consent flow, exchanges the returned authorization code at the token endpoint (POST https://api.box.com/oauth2/token with grant_type=authorization_code), and stores the resulting access-token header value under this reference.\n\nThe access token acts as the authorizing user and expires; the external process owns refresh (including any refresh token the grant returns) and renews the stored value before expiry — the injector injects the stored value verbatim and performs no OAuth itself. Token lifecycle from the retrieved token references (retrieved 2026-09-21): the refresh token is valid for 60 days, is single-use, and is rotated on every use — each refresh returns a new access token together with a new refresh token, so the external custody job must store the rotated pair every time or the chain breaks and the user must be re-authorized; and an access token can be revoked at any time by POSTing it (or the refresh token) with the app's client_id and client_secret to https://api.box.com/oauth2/revoke — the custody job should use that endpoint for explicit revocation on suspicion rather than relying on expiry.\n\nThe retrieved pages did not state the exact access-token lifetime or whether disabling the app in the Developer Console invalidates already-issued access tokens — confirm both against Box's token reference before enabling and treat disabling issuance as not necessarily invalidating already-issued tokens; an expired or revoked value fails closed.\n\nLeast privilege: configure the app with only the scopes these capabilities need, and note the retrieved guide's observation that the token is inherently tied to the authorizing user — authorize with a dedicated service account holding access only to the governed folders.\n\nExecutor hygiene: the value must live only in executor memory for the lifetime of a call, must never be written to logs, traces or diagnostics, and must not appear in crash dumps; a deployment that cannot meet that bar must not enable the pack."
  },
  "capabilities": [
    {
      "capability_id": "box.folders.items.read",
      "version": "1.0.0",
      "kind": "tool",
      "risk_tier": "R0",
      "owner": "REPLACE-WITH-ACCOUNTABLE-HUMAN",
      "data_class": "pii",
      "egress_allowlist": [
        "box-api.invalid"
      ],
      "endpoint": "https://box-api.invalid/2.0/folders/FOLDER_ID/items",
      "method": "GET",
      "connector": "http",
      "custody": "customer_vault",
      "secret_ref_id": "secret-ref-box-oauth-token",
      "inject": "header",
      "inject_name": "Authorization",
      "actions": [
        "read"
      ],
      "resource_id": "box-enterprise",
      "description": "List the items in one folder as a collection read; the reviewed documentation shows marker and offset pagination and file entries that can include names, sizes, owners and any existing shared_link URLs — internal content metadata. FOLDER_ID is a placeholder the deployment binds before enabling. Folder item entries carry owner user identities, so the read is classified as pii (personal data).",
      "requires_review": true
    },
    {
      "capability_id": "box.files.metadata.read",
      "version": "1.0.0",
      "kind": "tool",
      "risk_tier": "R0",
      "owner": "REPLACE-WITH-ACCOUNTABLE-HUMAN",
      "data_class": "pii",
      "egress_allowlist": [
        "box-api.invalid"
      ],
      "endpoint": "https://box-api.invalid/2.0/files/FILE_ID",
      "method": "GET",
      "connector": "http",
      "custody": "customer_vault",
      "secret_ref_id": "secret-ref-box-oauth-token",
      "inject": "header",
      "inject_name": "Authorization",
      "actions": [
        "read"
      ],
      "resource_id": "box-enterprise",
      "description": "Read one file's metadata object. The retrieved response example shows the object can carry the file's shared_link URL, expiring embed links, classification labels, tags and owner identities — sensitive metadata even though the file content is not returned. This capability reads metadata only; downloading file content (GET /2.0/files/{id}/content) is not registered by this pack. FILE_ID is a placeholder the deployment binds before enabling. The owner identities in the object are personal data, so the read is classified as pii (personal data).",
      "requires_review": true
    },
    {
      "capability_id": "box.files.delete",
      "version": "1.0.0",
      "kind": "tool",
      "risk_tier": "R3",
      "owner": "REPLACE-WITH-ACCOUNTABLE-HUMAN",
      "data_class": "internal",
      "egress_allowlist": [
        "box-api.invalid"
      ],
      "endpoint": "https://box-api.invalid/2.0/files/FILE_ID",
      "method": "DELETE",
      "connector": "http",
      "custody": "customer_vault",
      "secret_ref_id": "secret-ref-box-oauth-token",
      "inject": "header",
      "inject_name": "Authorization",
      "actions": [
        "delete"
      ],
      "resource_id": "box-enterprise",
      "description": "Delete one file; the reviewed documentation shows an empty response on success and an optional if-match header carrying the file's etag so the call fails with 412 if the file changed since it was observed. Delete is one of the designated actions requiring human approval.\n\nOn supported AAES-mediated execution paths, irreversible actions require approval by an authorized person; this does not prevent calls through bypass or observation-only paths; even where the enterprise's trash settings allow later recovery, this pack makes no general-reversibility claim. FILE_ID is a placeholder the deployment binds before enabling.",
      "requires_review": true
    },
    {
      "capability_id": "box.folders.delete",
      "version": "1.0.0",
      "kind": "tool",
      "risk_tier": "R3",
      "owner": "REPLACE-WITH-ACCOUNTABLE-HUMAN",
      "data_class": "internal",
      "egress_allowlist": [
        "box-api.invalid"
      ],
      "endpoint": "https://box-api.invalid/2.0/folders/FOLDER_ID",
      "method": "DELETE",
      "connector": "http",
      "custody": "customer_vault",
      "secret_ref_id": "secret-ref-box-oauth-token",
      "inject": "header",
      "inject_name": "Authorization",
      "actions": [
        "delete"
      ],
      "resource_id": "box-enterprise",
      "description": "Delete one folder. The retrieved documentation states the recursive query parameter deletes a non-empty folder and all of its content — a broad-impact delete registered at the minimum R3 tier; delete is one of the designated actions requiring human approval.\n\nOn supported AAES-mediated execution paths, irreversible actions require approval by an authorized person; this does not prevent calls through bypass or observation-only paths. The registration fixes method and path but does not restrict the recursive query parameter: the deployment should require per-request human approval for recursive calls and review whether recursive=false-only is an estate-local restriction worth enforcing in policy. FOLDER_ID is a placeholder the deployment binds before enabling.",
      "requires_review": true
    },
    {
      "capability_id": "box.files.shared_link.create",
      "version": "1.0.0",
      "kind": "tool",
      "risk_tier": "R3",
      "owner": "REPLACE-WITH-ACCOUNTABLE-HUMAN",
      "data_class": "internal",
      "egress_allowlist": [
        "box-api.invalid"
      ],
      "endpoint": "https://box-api.invalid/2.0/files/FILE_ID",
      "method": "PUT",
      "connector": "http",
      "custody": "customer_vault",
      "secret_ref_id": "secret-ref-box-oauth-token",
      "inject": "header",
      "inject_name": "Authorization",
      "actions": [
        "update",
        "share"
      ],
      "resource_id": "box-enterprise",
      "description": "Create or update a file’s shared link, or change other file properties through the same general Update File operation, PUT /2.0/files/{id} (reference retrieved 2026-09-21). An open shared link yields a public URL and direct download_url. Once another party has obtained the information, changing the link cannot make that disclosure private again.\n\nRequest limits: this is not a link-only endpoint. Its unrestricted body can also change name, description, tags, lock state, or parent folder; changing the parent moves the file. The caller chooses link access (open, company, or collaborators) and permissions. Enforce intended limits through policy; prose about an intended use does not restrict the body.\n\nClassification: update and share, minimum R3.\n\nOn supported AAES-mediated execution paths, an authorized person must approve the irreversible action. This cannot stop observation-only or bypass calls.\n\nFolder shared links are excluded; see the pack notes. Bind FILE_ID before enabling.",
      "requires_review": true
    }
  ],
  "resources": [
    {
      "resource_id": "box-enterprise",
      "kind": "api",
      "locator": "https://box-api.invalid/2.0",
      "data_class": "pii",
      "owner": "REPLACE-WITH-ACCOUNTABLE-HUMAN"
    }
  ],
  "review": {
    "state": "library",
    "date": "2026-09-23",
    "sources": [
      "https://developer.box.com/reference/get-folders-id-items/ (retrieved 2026-09-21)",
      "https://developer.box.com/reference/get-files-id/ (retrieved 2026-09-21)",
      "https://developer.box.com/reference/delete-files-id/ (retrieved 2026-09-21)",
      "https://developer.box.com/reference/delete-folders-id/ (retrieved 2026-09-21)",
      "https://developer.box.com/reference/put-files-id--add-shared-link/ (retrieved 2026-09-21)",
      "https://developer.box.com/guides/authentication/oauth2/without-sdk/ (retrieved 2026-09-21)",
      "https://developer.box.com/reference/put-files-id/ (retrieved 2026-09-21)",
      "https://developer.box.com/guides/authentication/tokens/refresh/ (retrieved 2026-09-21)",
      "https://developer.box.com/guides/authentication/tokens/revoke/ (retrieved 2026-09-21)"
    ],
    "reviewer_id": "aaes-eng"
  }
}