{
  "schema": "hybrid.partner-vault-integration.v1",
  "partner": "Any registered confidential application",
  "production_registration": "Each client must register its own exact HTTPS origin and callback; example URLs are not production values.",
  "required_partner_details": {
    "application_name": "",
    "production_https_origin": "",
    "exact_sign_in_callback_url": "",
    "optional_post_logout_url": "",
    "separate_staging_registration": true
  },
  "callback_example": "https://<their-app-host>/auth/hybrid-id/callback",
  "authentication": {
    "issuer": "https://auth.hybrid-id.com",
    "flow": "API-only owner connection authorization and confidential backend file access; Authorization Code + PKCE S256 remains an optional separate sign-in flow",
    "client_type": "confidential web application",
    "token_endpoint_auth_method": "client_secret_basic",
    "vault_enabled": true,
    "requested_scopes": [
      "openid",
      "vault:files:upload",
      "vault:files:read"
    ],
    "owner_consent": "Required; sign-in alone grants no Data Vault access. App and owner revocation and session expiry apply on every request.",
    "owner_setup": {
      "account_workspace": "https://hybrid-id.com/account",
      "requirements": [
        "An active Hybrid ID account.",
        "Authenticator enabled and account protection configured in its personal workspace.",
        "Its own provisioned Data Vault and current native storage eligibility."
      ],
      "on_missing_setup": "Use the owner-device API guide for first authenticator, protection and consent setup. Never collect owner secrets in the partner backend.",
      "mpc_wallet_required": false,
      "owner_device_api": "https://auth.hybrid-id.com/vault/owner"
    },
    "account_mapping": "Use the validated pairwise OIDC sub for application account continuity. An encryption descriptor is storage context, not a replacement sign-in identity."
  },
  "api": {
    "url": "https://api.hybrid-chain.com/api/v2/data-vault/files",
    "method": "POST",
    "application_authentication": "HTTP Basic using the registered application credentials, from its backend only",
    "user_authentication": "Current owner-consented OAuth access_token in the JSON body; never an Identity-native account token",
    "operations": [
      "context",
      "prepare-upload",
      "register",
      "put-chunk",
      "commit",
      "list",
      "read",
      "read-chunk",
      "cancel",
      "proof",
      "request-decryption",
      "decryption-status",
      "refresh-connection"
    ],
    "request_shape": "{operation, access_token, ...operation-specific fields}; additional fields rejected"
  },
  "storage": {
    "owner_boundary": "Identity-derived personal workspace and Data Vault; caller cannot choose vault IDs.",
    "disclosure_scope": "Only files allocated and created through this exact owner/application connection.",
    "encryption": "Encrypt content and filenames locally before upload, using the owner public encryption descriptor and the prepared file ID. Return ciphertext and the owner-wrapped file key; no owner private key or master password is disclosed to the application.",
    "plaintext_processing": "the application may decrypt a selected file only after its owner separately approves that exact file, recipient public key, purpose and expiry in Hybrid-ID. The owner device unwraps only that file key locally and HPKE-wraps it to the application; no owner master password, root or private key leaves the device. OAuth ciphertext-read permission alone is insufficient.",
    "transport_chunk_bytes": 1048576,
    "native_plaintext_file_limit_bytes": 1073741824,
    "retries": "Persist the request_id, allocated object_id and exact encrypted registration/chunks; do not re-encrypt when retrying an uncertain response.",
    "proof": "Completion adds a commitment-only record to the established Data Vault registry; poll proof until native finality is verified on hybrid-mainnet. Do not call a pending anchor final.",
    "decryption_revocation": "A revoked/expired approval, changed recipient or changed owner consent stops future file/key retrieval. Already decrypted or copied information cannot be recalled."
  },
  "wallet_dependency": false,
  "acceptance_status": "Passed platform API-only mainnet acceptance on 2026-10-20 with five new synthetic owners and five independently verified new native proofs. Every production client requires its own registration and owner authorization.",
  "sdk": {
    "sign_in_helper": "hybrid-id-node.mjs",
    "file_transport_helper": "hybrid-id-vault-node.mjs",
    "sign_in_options": {
      "vaultScopes": [
        "vault:files:upload",
        "vault:files:read"
      ]
    },
    "return_value": "finishSignIn returns accessToken only for an explicitly requested and granted Vault/Steam connection. Keep it on the application backend; do not serialize it to the browser.",
    "already_signed_in": "Bind additional consent to the existing application account with expectedSubject.",
    "default_sign_in": "Unchanged; ordinary sign-in requests no Vault permissions and returns no owner API token.",
    "recipient_helper": "hybrid-id-vault-recipient-node.mjs and vault-crypto/*; install the pinned crypto packages described in the guide.",
    "owner_device_helper": "hybrid-id-vault-owner-node.mjs",
    "backend_account_binding": "Verify file context.subject against the application account already authenticated by the backend. Never accept a claimed subject or merge by email."
  },
  "recipient_registration": {
    "field": "vault_recipient",
    "type": "X25519 public key",
    "shape": {
      "key_id": "32 lowercase hex characters",
      "public_key": "canonical unpadded base64url of 32 public bytes"
    },
    "private_key": "Generated and retained by the the application backend; never uploaded to Hybrid-ID or shared in chat."
  },
  "owner_approval": {
    "entry": "POST https://auth.hybrid-id.com/vault/owner, file-review operation",
    "flow": "Use owner-device file-review API commands, local decryption preview and explicit fresh-MFA approval; an optional Hybrid-ID review page uses the same ledger.",
    "bound_to": [
      "application",
      "pairwise owner subject",
      "native owner context",
      "exact file and manifest",
      "recipient key",
      "purpose",
      "expiry",
      "consent revision"
    ],
    "operations": "Private first-party only. The partner API cannot approve or revoke on behalf of the owner."
  },
  "five_account_acceptance": {
    "required_accounts": 5,
    "account_addresses": "User authorized five newly generated dummy accounts; example.invalid fixture addresses remain unverified unless normal verification occurs.",
    "status": "passed mainnet 2026-10-20",
    "guide": "docs/data-vault-integration-guide.md",
    "no_mpc": true,
    "interface": "APIs only; no browser or HTML form automation.",
    "receipt": "https://hybrid-id.com/integrations/data-vault-mainnet-acceptance-20261020.json",
    "standalone_example": "https://hybrid-id.com/integrations/data-vault-api-example-20261020.tar.gz"
  },
  "owner_api": {
    "endpoint": "https://auth.hybrid-id.com/vault/owner",
    "status": "deployed and verified through five new API-only synthetic owners on mainnet",
    "authentication": "Native owner hcb API session sent directly from owner device to Hybrid-ID; web platform credential class does not require web interface. Anonymous register follows existing Hybrid-ID policy.",
    "operations": [
      "register",
      "authenticator-session",
      "protection-status",
      "protection-package",
      "protection",
      "application-create",
      "connection-preview",
      "connection-authorize",
      "connection-revoke",
      "file-review"
    ],
    "private_key_custody": "Owner device. Only encrypted protection packages and selected-file recipient envelopes cross the API.",
    "backend_handoff": "Only app-scoped access/renewal tokens and authoritative pairwise subject; no native owner session or password.",
    "renewal": "App Basic plus app-scoped renewal capability; at most original eight-hour window, fresh native authority/consent/descriptor checks each time; never restores revoked authority.",
    "authenticator_bootstrap": "First enrollment only: the existing server-fixed Hybrid-ID management exchange issues a separate native management bearer to the owner device. Only enrollment/confirmation use it; protection and app/file approvals retain their original native source session binding."
  }
}