read_synthetic_signin_code

{
  "name": "read_synthetic_signin_code",
  "resource": "account",
  "tier": "observe",
  "grant": "synthetic_estate",
  "summary": "Read the unspent emailed sign-in codes the emailed-code route holds for the fixture domain `synthetic.turnzero.ai` in place of sending them, by `account`, a synthetic account's id, or by `address`, the address a first sign-in at the domain typed, one of the two and never both: newest first, each with its issued instant, its expiry instant, its binding hash, and the attempts remaining, or one ticket's code alone where `binding` names the reader's own binding hash (base64url of the SHA-256 of the binding cookie's value). By address the account is resolved through the address's `email` identity: `account` is null until the first sign-in's confirmation creates it, the codes held under the address answered until then and those held under the account after. Admitted for an account in the caller's reach under `synthetic_estate`, the batches its own credential seeded and every first-sign-in batch, refused 409 `account_outside_batches` otherwise, by id or by address, and for any synthetic account under `super_admin`; refused 409 `account_not_synthetic` for a standing account that is not synthetic under `super_admin` (under `synthetic_estate` such an account lies outside the reach and is refused `account_outside_batches`, the reach read first) and 409 `address_not_synthetic` for an address outside the fixture domain, an id no account stands for reading as no codes; readable with the `SYNTHETIC_ESTATE` mode `off`, every read one action record, and the typed address reaching no record.",
  "annotations": {
    "readOnlyHint": true,
    "destructiveHint": false,
    "openWorldHint": false,
    "idempotentHint": true
  }
}

{
  "name": "read_synthetic_signin_code",
  "tier": "observe",
  "scenario": "API-L0-12",
  "summary": "Read the unspent emailed sign-in codes held for the fixture domain, by `account` or by `address`. Platform operator or its harness (the `synthetic_estate` grant or `super_admin`) only. The codes are held instead of sent: a synthetic account's own, a stranger's first sign-in's, and an end user's in an application the account owns. By `address` the account is resolved through its email identity; until the confirmation creates it, `account` is null and the address's held codes are answered. It answers the codes newest first with their instants, binding hashes, and attempts remaining, or one ticket's by the reader's binding hash. Under `synthetic_estate` it reaches the batches the caller's credential seeded and every first sign-in's, refusing `account_outside_batches` beyond them, a customer's account among them, and `address_not_synthetic` outside the fixture domain. Under `super_admin` a customer's account is refused `account_not_synthetic`. Readable while the platform's synthetic-account mode is off; every read is an action record.",
  "owners": [
    "MAPI-16"
  ]
}

{
  "request": {
    "type": "object",
    "properties": {
      "account": {
        "type": "string",
        "description": "The synthetic account whose unspent codes are read; one of `account` and `address` is required, and never both. Under the `synthetic_estate` grant an account outside the caller's reach — the batches its own credential seeded and every first-sign-in batch — refuses 409 `account_outside_batches`, a standing customer account among them. Under `super_admin` a standing account that is not synthetic refuses 409 `account_not_synthetic`."
      },
      "address": {
        "type": "string",
        "format": "email",
        "description": "The address a first sign-in at the reserved fixture domain `synthetic.turnzero.ai` typed, in the label form; one of `account` and `address` is required, and never both. Lowercased; the account is resolved through its `email` identity, and the answer's `account` is null until the first sign-in's confirmation creates it, the codes held under the address answered until then and those held under the account after. An address outside the domain refuses 409 `address_not_synthetic`, carrying no address; one held by an account outside the caller's reach refuses 409 `account_outside_batches`, as the read by id does."
      },
      "binding": {
        "type": "string",
        "description": "Optional: the reader's own binding hash — base64url of the SHA-256 of the binding cookie's value the sign-in start set — selecting that ticket's code alone; absent, every unspent code is answered newest first."
      }
    }
  },
  "response": {
    "type": "object",
    "required": [
      "contract_version",
      "account",
      "codes"
    ],
    "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."
      },
      "account": {
        "type": [
          "string",
          "null"
        ],
        "description": "The synthetic account the codes are held under: the id named, or the one resolved through the address's `email` identity. It is null where the read was by address and no account holds it yet; the codes are then held under the address until the first sign-in's confirmation creates the account."
      },
      "codes": {
        "type": "array",
        "description": "The unspent codes the route holds for the account, or under the address where no account holds it yet, newest first; empty where none is held, where every code is spent or expired, or where `binding` names no held ticket.",
        "items": {
          "type": "object",
          "required": [
            "code",
            "issued_at",
            "expires_at",
            "binding",
            "attempts_remaining"
          ],
          "properties": {
            "code": {
              "type": "string",
              "pattern": "^[0-9]{6}$",
              "description": "The six-digit code the person types on the code page."
            },
            "issued_at": {
              "type": "string"
            },
            "expires_at": {
              "type": "string",
              "description": "The ticket's expiry, ten minutes after the start (ACS-L0-12)."
            },
            "binding": {
              "type": "string",
              "description": "The ticket's binding hash, the browser that started the sign-in."
            },
            "attempts_remaining": {
              "type": "integer",
              "minimum": 0,
              "description": "The confirmations the code still admits, five at issue (ACS-L0-12)."
            }
          }
        }
      },
      "detail": {
        "type": "string"
      }
    }
  }
}