#Hub contracts (shared by every part of the build)

The fixed interfaces between the hub (SIGNATURE_MODE=hub), client apps (SIGNATURE_MODE=client) and the Kukux Sign Agent. Plan: plans/signature-hub.md. Change this file first if a contract has to change.

All hub URLs are relative to the hub's APP_URL (https://signature.uplb.edu.ph). Every error body is {"error": "<code>", "message": "<human text>"}.

#1. Already in place (foundation)

Mode in tests: sub-providers are chosen in register(), and Testbench registers package providers before getEnvironmentSetUp / defineEnvironment run, so set signature.mode earlier: a trait that overrides resolveApplicationConfiguration() (see tests/Feature/Hub/Api/HubApiEnvironment.php), applied with uses(). A TestCase subclass doesn't work under Feature/: tests/Pest.php already applies TestCase there.

#2. Hub API for apps

#2.1 OAuth (built into the package, no Passport)

Tokens: opaque, 40+ random chars, stored as SHA-256 in HubToken. Scopes on an app: signatures.read, sign. App tokens carry the app's scopes.

#2.2 People, signatures, signing (app token)

Sign-request statuses: pending, signed, declined, refused, expired, failed.

#2.3 Hub-side PHP services other parts call

#3. Webhooks (hub → app)

POST <app webhook_url> with headers:

1
2
3
4
5

Content-Type: application/json
X-Signature-Hub-Id: <event uuid>
X-Signature-Hub-Event: <event>
X-Signature-Hub-Timestamp: <unix seconds>
X-Signature-Hub-Signature: sha256=<hex(hmac_sha256(webhook_secret, timestamp + "." + raw_body))>

Body: {"id","event","created_at","data":{…}}. 2xx = delivered.

App side: POST /signature/hub/webhook (client mode), tolerance hub.webhook_tolerance, dedupe on X-Signature-Hub-Id via HubEvent.

#4. Agent wire changes (package ↔ Kukux Sign Agent)

All additive: a standalone server never sends the new fields.

1. requesting_app. A claimed job may carry "requesting_app": {"name": "performance"}. Confirm view: "performance asks: <document title>".

2. Login (usernameless hub sign-in).

   • Link: kukuxsign://login/<challenge-uuid>?t=<token>&s=<serverId> (same UUID / token / server-id rules as job).
   • Agent → POST /signature/agent/logins/{challenge}/claim body {"link_token": t}, authenticated exactly like POST /signature/agent/jobs/{job}/claim (bearer + request proof).
   • 200: a normal job payload with "purpose": "login", "document": {"title": "Sign in to <app name>"} and "login": {"match_code": "47-12", "browser": "Chrome on macOS", "ip": "10.1.2.3"}. Errors: 404 login_not_found, 409 login_unavailable, 403 invalid_link_token.
   • Then the agent shows the match code, asks for Touch ID / Windows Hello, and finishes with the existing POST /signature/agent/jobs/{job.uuid}/complete (proof over canonicalMessage('login', nonce, user_id, payload_hash)) or /reject.
3. Transfer. A normal kukuxsign://job/… link; job "purpose": "transfer", "document": {"title": "Move your signature to a new computer"}, "transfer": {"name": "Juan Dela Cruz", "device": "MacBook Air"}. Completed/rejected through the existing job endpoints.
4. Canonical purposes gain login and transfer; shared vectors in tests/fixtures/agent-canonical-vectors.json (package) and test/fixtures/canonical-vectors.json (agent) must stay identical.
5. Name refresh. GET /signature/agent/status already returns user.name; the agent updates its stored userName when it differs.

Server side, AgentJobService::complete() / reject() fire Events\AgentJobUpdated. The identity work listens for login / transfer; the hub API listens for sign_receipt jobs linked to a HubSignRequest (agent_job_id).

#5. Deferred (hash-only) signing

• DeferredPdfSigner::prepare() stamps the image, writes a PDF whose signature /Contents is a zero-filled placeholder of at least 32 768 hex chars, and returns PreparedPdf{path, digest, byteRange, placeholderLength} where digest = sha256(bytes covered by /ByteRange).
• The hub signs that digest with DigestSigner::signDigest() → DER ContentInfo(SignedData), detached, signed attributes contentType, signingTime, messageDigest, signingCertificateV2; optional RFC 3161 timestamp as unsigned attribute.
• DeferredPdfSigner::inject($path, $cmsDer) writes the CMS hex into the placeholder (zero-padded) and returns the signed PDF's path.

#6. Who owns what (parallel build)

Shared files (SignatureServiceProvider, SignaturePlugin, config, the migration, models) are foundation: if a stream needs a change there, keep it minimal, re-read the file right before editing, and mention it in its report.