Reachability

Auth: Own-device signed read, operation query-reachable.

Request and response

Angle-bracket values describe placeholders, including nested objects and numeric types; these are wire shapes, not captured service data. Replace them before sending.

POST /v1/query/reachable HTTP/1.1
Host: trust-staging.rebellion.systems
Content-Type: application/json

{
  "sourceGraphKeyId": "<own-node-id>",
  "targetGraphKeyId": "<target-node-id>",
  "policy": {
    "maxHops": 3,
    "minTrust": 50,
    "scope": "identity"
  },
  "authorization": {
    "graphKeyId": "<device-id>",
    "nonce": "<fresh-random-nonce>",
    "signedAt": "<current-ISO-timestamp>",
    "signature": "<base64-DER-signature>"
  }
}

Response shape:

{
  "reachable": "<boolean>",
  "pathLength": "<integer-or-null>",
  "effectivePolicy": "<effective-policy-object>",
  "attestation": "<signed-attestation-object>",
  "proof": "<legacy-proof-or-null>",
  "integrity": {
    "authoritative": "attestation",
    "unsignedProjections": [
      "reachable",
      "pathLength",
      "effectivePolicy",
      "proof"
    ]
  }
}

POST /v1/query/reachable asks from the authenticated device's own node. Sign read operation query-reachable over the exact query body before adding authorization.

Include all intended policy values explicitly. Out-of-range values return 400 rather than being clamped. A horizon can only narrow the answer: edges must qualify now and at that future time. A past horizon is rejected. The server chooses evaluation time and the current graph commitment.

import {
  createTrustGraphSdk,
  signBrowserGraphRead,
} from '@rebellion-systems/trust-graph-sdk/browser';

export async function requestReachability(
  privateKey: CryptoKey,
  deviceId: string,
  ownNodeId: string,
  targetNodeId: string,
) {
  const graph = createTrustGraphSdk({
    serverUrl: 'https://trust-staging.rebellion.systems',
  });
  const query = {
    sourceGraphKeyId: ownNodeId,
    targetGraphKeyId: targetNodeId,
    policy: { maxHops: 3, minTrust: 50, scope: 'identity' as const },
  };
  const authorization = await signBrowserGraphRead(privateKey, {
    operation: 'query-reachable',
    graphKeyId: deviceId,
    graphNodeId: ownNodeId,
    query,
  });
  return graph.queryReachability({ ...query, authorization });
}

This function requests evidence; it does not verify that evidence. Verify response.attestation locally with the SDK verifier and your pinned keys before acting on it.

Response

The response includes reachable, pathLength, effectivePolicy, the legacy proof, the signed attestation, and integrity. Optional sourceHandle and targetHandle are display metadata.

integrity.authoritative is attestation. Its publicInputs carry the signed answer, endpoints, policy, evaluation time, horizon and commitment fields. Top-level convenience fields are unsigned projections.

Errors

Malformed policy returns 400. An invalid or missing read signature returns 401; a device from another source node is refused. Lifecycle and approval failures use the common authorization errors. Unknown or deactivated endpoints are unavailable. Proof-generation failure returns 503 instead of a signature-only positive.

See attestations for local verification and the server verification endpoint.