paybondpaybond
Sign in

Harbor API reference

Intent escrow, verification, evidence, settlement, disputes, and policy-registry routes served by harbor-intent-escrow (and proxied by the Gateway under /harbor).

Harbor API reference

Harbor is the tenant-scoped intent-escrow service. It is the only component that writes to the provenance ledger or to Stripe/ACH settlement rails, and every state transition is signed and idempotent.

  • Normative implementation: crates/harbor-intent-escrow.
  • Public exposure: the Paybond Gateway exposes these routes under the /harbor prefix (for example GET /harbor/operator/v1/summary → upstream GET /operator/v1/summary). Inside the private VPC, service accounts may call Harbor directly.
  • Auth: Bearer JWT in Authorization; tenant realm is the token tid claim. Kit SDKs mint the token from /v1/auth/harbor-access (see Authentication).

Route map

Intents

MethodPathDescription
POST/intentsCreate a principal-signed intent (binds to a predicate_dsl or predicate_ref).
POST/intents/{intent_id}/evidenceSubmit payee-signed evidence; evaluates the intent predicate and returns a predicate_evaluation report.
POST/intents/{intent_id}/settlement/confirmConfirms the release (or refund) transition after predicate evaluation.
POST/verifyPaybond Kit capability verification (PaybondCapabilityBinding). Validates capability_token against the intent row.

Idempotency: POST /intents, POST /intents/{id}/evidence, and POST /intents/{id}/settlement/confirm honor the idempotency-key header. Wire shape: harbor-idempotency-openapi.yaml.

Predicate evaluation rules: harbor-predicate-dsl.md.

Operator console

Read-only views plus dispute lifecycle for the authenticated tenant's operator dashboard.

MethodPathDescription
GET/operator/v1/summaryTenant-scoped counts and totals (MetricPanel feed).
GET/operator/v1/intentsPaginated list with filters (status, operator, time window).
GET/operator/v1/intents/{id}One intent with timeline and evidence rows.
POST/operator/v1/intents/{id}/dispute/openOpens a dispute case; returns the case_id.
POST/operator/v1/intents/{id}/dispute/resolveResolves a dispute with an outcome (release/refund/split) and note.

Gateway forwards these under /harbor/operator/v1/* with tenant/RBAC checks.

Ledger (read-only, PAYBOND-007)

MethodPathDescription
GET/ledger/v1/tipCurrent tip: sequence and entry commitment; empty when the tenant ledger has no rows yet.
GET/ledger/v1/authorityHex-encoded Ed25519 verifying key for this Harbor deployment (offline signature checks).
GET/ledger/v1/eventsTenant-scoped append-only page. Query: after_seq (exclusive cursor, default 0), limit (1–256, default 64).
GET/ledger/v1/merkle/latestLatest completed Merkle batch checkpoint JSON (checkpoint may be null); includes deterministic signature fields when Harbor can derive the signed checkpoint envelope.
GET/ledger/v1/verifyTenant-scoped continuity verification result: signed row chain, closed-batch checkpoint coverage, and actionable failure guidance.
GET/ledger/v1/verifier-packExport the tenant’s self-contained continuity proof pack: signed ledger rows, signed checkpoints, witness freshness metadata, checkpoint-lineage witnesses, and observed signing-key epochs for offline reruns.
POST/ledger/v1/verifier-pack/verifyRe-verify an exported verifier pack without direct sled access. Fails closed on stale witness material, checkpoint witness drift, or key-transparency mismatches and returns the same verified/failed guidance contract as /ledger/v1/verify.

Normative wire: harbor-openapi.yaml (Ledger tag). Ledger guarantees and append semantics: Ledger & provenance.

Policy registry (V1-006)

Versioned tenant policies built on top of the predicate VM. Complete OpenAPI: harbor-policy-openapi.yaml.

MethodPathSummary
GET/policy/v1/templatesList global policy template catalog (read-only, no tenant state).
POST/policy/v1/previewMaterialize DSL and human summary from { template_id, parameters } without persisting.
POST/policy/v1/testEvaluate sample evidence against a materialized template (sandbox harness).
GET/policy/v1/versions?template_id=…List tenant versions for one template.
POST/policy/v1/versionsCreate a draft from { template_id, parameters }.
GET/policy/v1/versions/{template_id}/{seq}Fetch one version row (state, materialized_dsl, content_digest_hex).
POST/policy/v1/versions/{template_id}/{seq}/publishPublish an approved draft; updates tenant head for new intents.
POST/policy/v1/versions/{template_id}/{seq}/deprecateDeprecate a version (must not be current head).
POST/policy/v1/versions/{template_id}/{seq}/retireRetire a deprecated version.
POST/policy/v1/rollbackMove published head to a prior approved version.

RBAC (enforced at Gateway):

  • Read (GET …/templates, GET …/versions, GET …/versions/{…}) — operator or tenant_admin.
  • Sandbox (POST …/preview, POST …/test) — operator or tenant_admin.
  • Lifecycle mutations (POST …/versions, POST …/rollback, publish/deprecate/retire) — tenant.admin entitlement only.

content_digest_hex on every version row is bound into intent signing v3, so rolling a version back is observable from any intent created after the switch.

Tenant isolation

Every row read or written by Harbor is filtered by the authenticated tenant realm. Harbor refuses to:

  • Bind evidence from intent A to intent B across tenants.
  • Redeem a capability token whose tenant_id claim differs from the session.
  • Append to the ledger without a signed tenant envelope.

See Tenant model for the full invariant matrix.