openapi: 3.1.1
info:
  title: CallbackSignature
  version: 2.0.0
  description: Container schemas fetched from beckn.yaml. This cannot be extended as it is a reserved
    schema in beckn protocol. Any additional properties added to this schema can only be made using its
    *Attributes property
  license:
    name: CC-BY-NC-SA 4.0 International
  contact:
    name: Beckn Labs
    url: https://beckn.io
components:
  schemas:
    CallbackSignature:
      x-iri: https://schema.nfh.global/CallbackSignature/v2.0
      title: Beckn HTTP Callback Signature
      description: "A digitally signed authentication credential transmitted in the HTTP Authorization\
        \ header of PN solicited callbacks to CN `/on_*` endpoints. Extends the standard Signature by\
        \ chaining the PN's signature to the CN's original request signature, allowing the CN to verify\
        \ that the callback is a genuine response to a request it sent.\n\nThe PN produces this by signing\
        \ a four-line canonical signing string with its Ed25519 private key:\n\n    (created): {unix_timestamp}\n\
        \    (expires): {unix_timestamp}\n    digest: BLAKE2b-512={base64_callback_body_hash}\n    request-signature:\
        \ {cn_raw_base64_signature}\n\nThe fourth line (`request-signature`) contains the raw Base64 Ed25519\
        \ signature value extracted verbatim from the `signature=\"...\"` field of the CN's original `Authorization`\
        \ header. This binds the callback cryptographically to the triggering request.\n\nThe `headers`\
        \ attribute MUST be `\"(created) (expires) digest request-signature\"`. The `keyId` identifies\
        \ the PN signer. The algorithm MUST be `ed25519`. The body digest covers the callback body using\
        \ BLAKE2b-512.\n\nUsed for: PN→CN solicited callbacks only. For PN-initiated notifications (no\
        \ preceding CN request), use the standard Signature schema instead. For synchronous response signing,\
        \ see components/headers/AckSignatureHeader. See NFH-004 Authentication and Trust §6 for the full\
        \ callback signing procedure."
      type: string
      pattern: ^Signature keyId="[^"]+",algorithm="ed25519",created="\d+",expires="\d+",headers="\(created\)
        \(expires\) digest request-signature",signature="[A-Za-z0-9+/]+=*"$
      example: Signature keyId="example.ns/gro.example/bpp-key-001|ed25519",algorithm="ed25519",created="1714000060",expires="1714000660",headers="(created)
        (expires) digest request-signature",signature="BPPSIGNATURE=="