mint_upload_grant

Generated automatically from the published contract sources.

Build metadata: Registered in this build. Registration describes the default dispatcher in this build. It does not guarantee that a caller has the required credential or grant, that a tool is listed for that connection, or that the required service is configured.

A script calls this action over HTTPS at POST https://turnzero.ai/api/v1/actions/mint_upload_grant, with a bearer credential and the action's payload as the JSON body.

Contract description

Mint a short-lived upload grant for one file, so a shell uploads it without holding a long-lived token. Name the application, a storage area bound to it, and the file's name. The file lands in the partition `environment` names, or, where it names none, in that of the environment the application's deploys go to: production with one environment, development with two. The write records the identity `deploy` unless `identity` names another. The grant is single-use: the one write that lands spends it, and it expires after five minutes by default.

Name `local_path`, the file on your machine, where it is not the name's last segment in the folder the line runs from. The answer carries the grant once, its expiry, the size it admits, the file's whole address, and `command`, one line that uploads the file with the turnzero-cloud command, with `command_windows`, its Windows form. Run it once, as given. Where the name holds a space or another character one line cannot carry, no line is answered; run `commands.curl` in a POSIX shell or `commands.powershell` in Windows PowerShell instead, each sending the grant as the bearer and no other header. The application's own platform credential cannot call this tool.

Access and action metadata

{
  "name": "mint_upload_grant",
  "resource": "environment",
  "tier": "reversible",
  "summary": "Mint an upload grant for one file of a declared storage area bound to the named application: a single-use bearer credential for one PUT of that file, expiring after the configured lifetime, five minutes by default. It is admitted to the credentials `deploy` admits for that application, a deploy upload's grant and a deploy code aside, and the application's platform credential is refused. The file lands in the partition `environment` names, or, where it names none, in that of the environment the application's deploys go to; the write records the identity `deploy` unless `identity` names another.\n\nThe answer carries the grant once, its expiry, the size it admits, the file's whole address, and `command`, one line that uploads the file with the turnzero-cloud command's `put`, with `command_windows`, its Windows form. An optional `local_path` names the file the line reads. Where the name or that path holds a character one line cannot carry alike in every shell, no line is answered. Two ready commands stand either way: `curl` for a POSIX shell, and Windows PowerShell's `Invoke-WebRequest -UseBasicParsing`, each sending the grant as the bearer and no other header. The one write that lands spends the grant, and every other route refuses it.",
  "annotations": {
    "readOnlyHint": false,
    "destructiveHint": false,
    "openWorldHint": false
  }
}

MCP catalog entry

{
  "name": "mint_upload_grant",
  "tier": "reversible",
  "scenario": "OST-L0-08",
  "summary": "Mint a short-lived upload grant for one file, so a shell uploads it without holding a long-lived token. Name the application, a storage area bound to it, and the file's name. The file lands in the partition `environment` names, or, where it names none, in that of the environment the application's deploys go to: production with one environment, development with two. The write records the identity `deploy` unless `identity` names another. The grant is single-use: the one write that lands spends it, and it expires after five minutes by default.\n\nName `local_path`, the file on your machine, where it is not the name's last segment in the folder the line runs from. The answer carries the grant once, its expiry, the size it admits, the file's whole address, and `command`, one line that uploads the file with the turnzero-cloud command, with `command_windows`, its Windows form. Run it once, as given. Where the name holds a space or another character one line cannot carry, no line is answered; run `commands.curl` in a POSIX shell or `commands.powershell` in Windows PowerShell instead, each sending the grant as the bearer and no other header. The application's own platform credential cannot call this tool.",
  "owners": [
    "OST-L0-08",
    "OST-L0-03",
    "OST-L0-02",
    "OST-L0-04",
    "API-L0-17",
    "SEC-L0-07",
    "PLD-L0-40"
  ]
}

request

JSON pointer	Description and constraints
"" (root)	Type: object Required fields: ["application","area","name"]
/properties/application	The id of the application the upload is for, from `list_applications`. The area must be bound to it. Type: string
/properties/area	The declared storage area the file goes into, bound to the named application. An area the account has not declared is refused `undeclared_area`, and one bound to another application `area_scope_refused`. Type: string Pattern: ^[a-zA-Z0-9][a-zA-Z0-9_-]{0,63}$
/properties/name	The file's name within the area, verbatim, slashes included. The grant reaches this one file. An upload grant is refused for a name a write refuses: one holding a backslash, or a segment that ends with a dot. Type: string Minimum length: 1
/properties/environment	Optional. The environment whose partition of the area receives the file, `development` or `production`. Absent, the application's deploy target: production on an application with one environment, development on one with two, the partition its deploy reads an artifact from. Type: string Pattern: ^(development\|production)$
/properties/identity	Optional. The acting identity the write records. Absent, `deploy`. The grant fixes it, so the upload sends no identity header. Type: string Minimum length: 1
/properties/local_path	Optional. The file on your machine to upload, absolute or relative to the folder the line runs in. `command` carries it as its `--path`, and both `commands` read it. Absent, each reads the file named by the last segment of `name` in the folder it runs in. The platform never reads the path. A path holding a control character, a double quote, `$`, a backtick, `%`, `!`, `&`, `\|`, `<`, `>`, `^`, a typographic double quote, a doubled backslash, or a trailing backslash is refused `invalid_request`. So is `~` or a path opening with `~/` or `~\`, which no shell expands in double quotes. Type: string Minimum length: 1 Maximum length: 1024 Pattern: ^(?:[^"$`%!&\\|<>^\u201c-\u201e\u0000-\u001f\u007f\\]\|\\[^"$`%!&\\|<>^\u201c-\u201e\u0000-\u001f\u007f\\])+$

response

JSON pointer	Description and constraints
"" (root)	Type: object Required fields: ["contract_version","grant","expires_at","max_bytes","address","commands"]
/properties/contract_version	Required value: 1
/properties/reference	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. Type: string Pattern: ^[0-9a-f]{10}$
/properties/grant	The grant's value, answered this once and held by no record: the bearer of one PUT to `address`. Type: string
/properties/expires_at	When the grant stops serving, as an ISO 8601 instant. An unspent grant past it is refused `transfer_grant_expired`. Type: string
/properties/max_bytes	The most bytes the one write may carry, the configured bound. Type: integer
/properties/address	The file's whole address on the platform's public origin, each segment of its name escaped. Type: string
/properties/command	One line, for macOS and Linux, that uploads the file with the turnzero-cloud command's `put`: `echo <grant> \| npx -y <origin>/packages/turnzero-cloud-<version>.tgz put --area <area> --name <name>`, then `--origin <origin>` off `https://turnzero\.ai\`, then `--path "<file>"`, the file both `commands` read. Run it once, as given, before `expires_at`. It reads the grant on its standard input and writes the file, ending 0 where the file was written, 2 where that is unknown, and 3 where nothing was written. Absent where the file's name holds a character one line cannot carry alike in every shell, a space among them; `commands` stand either way. Type: string
/properties/command_windows	Present with `command`: 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, so a run of either spends the grant. Type: string
/properties/commands	Type: object Required fields: ["curl","powershell"] Additional properties: false
/properties/commands/properties/curl	A curl command for a POSIX shell: the grant in the Authorization header, and as the body the file `local_path` names, or else the file named by the last segment of `name` in the folder it runs in. Type: string
/properties/commands/properties/powershell	An Invoke-WebRequest command for Windows PowerShell, with -UseBasicParsing, which Windows PowerShell 5.1 needs: the same header and the same file. Type: string
/properties/detail	Names the file, its partition, and the identity, and says that the one write that lands spends the grant and that it expires at `expires_at`. It then names the line to run, or says why none is answered, and the local file each reads. Type: string

Complete payload contract

{
  "request": {
    "type": "object",
    "required": [
      "application",
      "area",
      "name"
    ],
    "properties": {
      "application": {
        "type": "string",
        "description": "The id of the application the upload is for, from `list_applications`. The area must be bound to it."
      },
      "area": {
        "type": "string",
        "pattern": "^[a-zA-Z0-9][a-zA-Z0-9_-]{0,63}$",
        "description": "The declared storage area the file goes into, bound to the named application. An area the account has not declared is refused `undeclared_area`, and one bound to another application `area_scope_refused`."
      },
      "name": {
        "type": "string",
        "minLength": 1,
        "description": "The file's name within the area, verbatim, slashes included. The grant reaches this one file. An upload grant is refused for a name a write refuses: one holding a backslash, or a segment that ends with a dot."
      },
      "environment": {
        "type": "string",
        "pattern": "^(development|production)$",
        "description": "Optional. The environment whose partition of the area receives the file, `development` or `production`. Absent, the application's deploy target: production on an application with one environment, development on one with two, the partition its deploy reads an artifact from."
      },
      "identity": {
        "type": "string",
        "minLength": 1,
        "description": "Optional. The acting identity the write records. Absent, `deploy`. The grant fixes it, so the upload sends no identity header."
      },
      "local_path": {
        "type": "string",
        "minLength": 1,
        "maxLength": 1024,
        "pattern": "^(?:[^\"$`%!&\\|<>^\\u201c-\\u201e\\u0000-\\u001f\\u007f\\\\]|\\\\[^\"$`%!&\\|<>^\\u201c-\\u201e\\u0000-\\u001f\\u007f\\\\])+$",
        "description": "Optional. The file on your machine to upload, absolute or relative to the folder the line runs in. `command` carries it as its `--path`, and both `commands` read it. Absent, each reads the file named by the last segment of `name` in the folder it runs in. The platform never reads the path. A path holding a control character, a double quote, `$`, a backtick, `%`, `!`, `&`, `|`, `<`, `>`, `^`, a typographic double quote, a doubled backslash, or a trailing backslash 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",
      "grant",
      "expires_at",
      "max_bytes",
      "address",
      "commands"
    ],
    "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."
      },
      "grant": {
        "type": "string",
        "description": "The grant's value, answered this once and held by no record: the bearer of one PUT to `address`."
      },
      "expires_at": {
        "type": "string",
        "description": "When the grant stops serving, as an ISO 8601 instant. An unspent grant past it is refused `transfer_grant_expired`."
      },
      "max_bytes": {
        "type": "integer",
        "description": "The most bytes the one write may carry, the configured bound."
      },
      "address": {
        "type": "string",
        "description": "The file's whole address on the platform's public origin, each segment of its name escaped."
      },
      "command": {
        "type": "string",
        "description": "One line, for macOS and Linux, that uploads the file with the turnzero-cloud command's `put`: `echo <grant> | npx -y <origin>/packages/turnzero-cloud-<version>.tgz put --area <area> --name <name>`, then `--origin <origin>` off `https://turnzero.ai`, then `--path \"<file>\"`, the file both `commands` read. Run it once, as given, before `expires_at`. It reads the grant on its standard input and writes the file, ending 0 where the file was written, 2 where that is unknown, and 3 where nothing was written. Absent where the file's name holds a character one line cannot carry alike in every shell, a space among them; `commands` stand either way."
      },
      "command_windows": {
        "type": "string",
        "description": "Present with `command`: 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, so a run of either spends the grant."
      },
      "commands": {
        "type": "object",
        "required": [
          "curl",
          "powershell"
        ],
        "properties": {
          "curl": {
            "type": "string",
            "description": "A curl command for a POSIX shell: the grant in the Authorization header, and as the body the file `local_path` names, or else the file named by the last segment of `name` in the folder it runs in."
          },
          "powershell": {
            "type": "string",
            "description": "An Invoke-WebRequest command for Windows PowerShell, with -UseBasicParsing, which Windows PowerShell 5.1 needs: the same header and the same file."
          }
        },
        "additionalProperties": false
      },
      "detail": {
        "type": "string",
        "description": "Names the file, its partition, and the identity, and says that the one write that lands spends the grant and that it expires at `expires_at`. It then names the line to run, or says why none is answered, and the local file each reads."
      }
    }
  }
}

Shared contracts

Refusals: every refusal, by surface, with its cause and its remedy
schemas/wire_error.schema.json
schemas/wire_errors.json
schemas/action_payloads.json (includes shared shapes)
management_api_contract.md