mint_download_grant

{
  "name": "mint_download_grant",
  "resource": "application",
  "tier": "reversible",
  "summary": "Mint a download grant for one completed export of the named application: a short-lived, read-only bearer credential, expiring after the configured lifetime, five minutes by default. It reads, by `GET` of a named file, the export's own files in the export area and the application's stored files in the export's environment that were created by the time the export listed them, the platform's deploy area excepted. A file stored after the export, or deleted and stored again, answers as an absent name does. A fresh export has the application's files as they now stand. Where the export recorded no instant for its stored files, the grant reads the export's own files alone, and `detail` says so. It lists nothing, every other route refuses it, and a read does not spend it. It is admitted to the credentials `read_export` admits for that application, and the application's platform credential is refused.\n\nThe answer carries the export, its environment, the grant's expiry, and `command`, one line that downloads the export with the turnzero-cloud command's `export download`, with `command_windows`, its Windows form. The grant is answered inside those two lines alone. An optional `local_path` names the folder the line writes into. An export that is running or failed is refused `export_not_completed`, and one whose files no longer stand `not_found`.",
  "annotations": {
    "readOnlyHint": false,
    "destructiveHint": false,
    "openWorldHint": false
  }
}

{
  "name": "mint_download_grant",
  "tier": "reversible",
  "scenario": "API-L0-18",
  "summary": "Download a completed export: mint a short-lived, read-only grant and get the one line that downloads every file under it, so no long-lived token is needed. Name the application and the export's id from `request_export`, and `local_path`, the folder to write into, outside the application's folder. The answer carries `command`, and `command_windows`, its Windows form. Run it once, as given: it writes the manifest and every file the manifest names, and a second line resumes where the first stopped.\n\nThe grant expires after five minutes by default. Until then it reads, by name, the export's own files and the application's stored files in the export's environment created by the time the export listed them. A file deleted and stored again after the export answers as absent, and the line counts it failed. A file first stored after the export is in no manifest, so the line does not read it. A fresh export has the application's files as they now stand. It lists nothing and writes nothing, and a read does not spend it. An export that is still running or that failed is refused `export_not_completed`: read it with `read_export` until its state is `completed`. The application's own platform credential cannot call this tool.",
  "owners": [
    "API-L0-23",
    "MAPI-21",
    "OST-L0-08",
    "OST-L0-03",
    "API-L0-17",
    "SEC-L0-07"
  ]
}

{
  "request": {
    "type": "object",
    "required": [
      "application",
      "export"
    ],
    "properties": {
      "application": {
        "type": "string",
        "description": "The id of the application the export read, from `list_applications`."
      },
      "export": {
        "type": "string",
        "description": "The export's id, from `request_export`. The export must be completed: a running or failed one is refused `export_not_completed`, and an id the application does not hold, or an export whose files no longer stand, is refused 404 `not_found`."
      },
      "local_path": {
        "type": "string",
        "minLength": 1,
        "maxLength": 1024,
        "pattern": "^(?:[^\"$`%!&\\|<>^\\u201c-\\u201e\\u0000-\\u001f\\u007f\\\\]|\\\\[^\"$`%!&\\|<>^\\u201c-\\u201e\\u0000-\\u001f\\u007f\\\\])+$",
        "description": "Optional. The folder on your machine the export is written to, absolute or relative to the folder the line runs in. `command` carries it as its `--path`, with `./` before a path that opens with a hyphen. Absent, the line writes a new folder, `export-<export id>`, in the folder it runs in, and is refused there where that folder holds `package.json`. The platform never reads the path. A path holding a character `deploy` refuses in its own `local_path` is refused `invalid_request`. So is `~` or a path opening with `~/` or `~\\`, which no shell expands in double quotes."
      }
    }
  },
  "response": {
    "type": "object",
    "required": [
      "contract_version",
      "export",
      "application",
      "environment",
      "expires_at",
      "command",
      "command_windows"
    ],
    "properties": {
      "contract_version": {
        "const": 1
      },
      "reference": {
        "type": "string",
        "pattern": "^[0-9a-f]{10}$",
        "description": "The short reference the platform recorded this call under, ten lowercase hexadecimal characters, the value the call’s record row carries; quote it when reporting the call."
      },
      "export": {
        "type": "string",
        "description": "The export the grant was minted for."
      },
      "application": {
        "type": "string"
      },
      "environment": {
        "type": "string",
        "enum": [
          "development",
          "production"
        ],
        "description": "The export's environment, the one the grant reads."
      },
      "expires_at": {
        "type": "string",
        "description": "When the grant stops serving, as an ISO 8601 instant. A read admitted before it is served to its end; a read after it is refused `transfer_grant_expired`."
      },
      "command": {
        "type": "string",
        "description": "One line, for macOS and Linux, that downloads the export with the turnzero-cloud command's `export download`: `echo <grant> | npx -y <origin>/packages/turnzero-cloud-<version>.tgz export download --export <application id>/<export id>`, then `--origin <origin>` off `https://turnzero.ai`, then `--path \"<folder>\"` where the call named `local_path`. Run it once, as given, before `expires_at`. It reads the grant on its standard input and writes the manifest and every file the manifest names into the folder. It ends 0 where every file is on disk, 1 where a file failed, 2 where it stopped before the end, and 3 where nothing was written. The grant appears in this line and in `command_windows` alone."
      },
      "command_windows": {
        "type": "string",
        "description": "The same line for every Windows shell, with `npx.cmd` where its head says `npx`. On Windows, run this one in `command`'s place, once, as given. The two are one command line under one grant."
      },
      "detail": {
        "type": "string",
        "description": "Says which line runs where and by when and the folder it writes. Where the export recorded an instant for its stored files, it says what the grant in the line reads: the export's own files and the application's stored files created by the time its export listed them. That form also says that a read does not spend the grant and that a fresh call answers another line once the grant expires. Where the export recorded none, it says that the line downloads the export's own files alone and that each stored file the manifest names answers as absent and counts as failed. That form then says that a fresh export has the application's stored files as they now stand, and names the two calls that make one."
      }
    }
  }
}