IF Commons GitHub

Estate Endpoints: the readers

0003Active

0003-estate-endpoints-readers · owner if · domain commons

Requirements

FR-001checkpassing

The OpenAPI reader MUST read OpenAPI 3 and Swagger 2 descriptions as JSON or YAML and give an endpoint (api: openapi) for each server (a templated address takes the default of its variable), with the authentication the description declares (none where it declares no security, otherwise the strongest of the schemes it uses: basic, token, session, oauth, mtls), and a problem for a server that is not an absolute address; it MUST NOT read operations or schemas.

Enforced (check): .github: cd commons/estate-endpoints && bun run verify — suite/readers.test.ts

Proved by: estate-endpoints/suite/readers.test.ts

Written in: estate-endpoints/src/logical/openapi.ts

Tests: passed: suite/readers.test.ts an OpenAPI description gives an endpoint for each absolute server with the authentication

FR-002checkpassing

The GraphQL reader MUST read a schema or an introspection, and, because a schema does not say where it is served, give the endpoint (api: graphql, authentication unknown) only at an address it is given, and otherwise say so as a problem.

Enforced (check): .github: cd commons/estate-endpoints && bun run verify — suite/readers.test.ts

Proved by: estate-endpoints/suite/readers.test.ts

Written in: estate-endpoints/src/logical/graphql.ts

Tests: passed: suite/readers.test.ts a GraphQL schema or introspection gives an endpoint only at the address it is given, with

FR-003checkpassing

The Android reader MUST read a manifest and give the app (the package, the oldest system, whether it allows traffic in the clear where the manifest says) and an endpoint for each web address its deep links claim, linked to the app (client-of).

Enforced (check): .github: cd commons/estate-endpoints && bun run verify — suite/readers.test.ts

Proved by: estate-endpoints/suite/readers.test.ts

Written in: estate-endpoints/src/logical/mobile.ts

Tests: passed: suite/readers.test.ts an Android manifest and an iOS Info.plist give the app with its system and cleartext setti

FR-004checkpassing

The iOS reader MUST read an Info.plist as XML and give the app (the bundle identifier, the oldest system), set it to allow the clear where App Transport Security allows arbitrary loads or an exception domain allows insecure ones, and give an endpoint in the clear for each such domain, linked to the app.

Enforced (check): .github: cd commons/estate-endpoints && bun run verify — suite/readers.test.ts

Proved by: estate-endpoints/suite/readers.test.ts

Written in: estate-endpoints/src/logical/mobile.ts

Tests: passed: suite/readers.test.ts an Android manifest and an iOS Info.plist give the app with its system and cleartext setti

FR-005checkpassing

The zone reader MUST read the master file format (with $ORIGIN, $TTL, records over several lines in parentheses, a missing owner as the one before, and comments) and give a domain for each name that owns a record, signed where the apex has a DNSKEY, and a dependency for each CNAME to another name of the zone; it MUST NOT copy addresses or text.

Enforced (check): .github: cd commons/estate-endpoints && bun run verify — suite/readers.test.ts

Proved by: estate-endpoints/suite/readers.test.ts

Written in: estate-endpoints/src/logical/dns.ts

Tests: passed: suite/readers.test.ts a zone gives a domain for each name that owns a record, signed where the apex has a key, a

FR-006checkpassing

The listening-ports reader MUST read ss -tuln text and osquery's listening_ports rows and give an endpoint for each port with the common service its port usually carries and its protocol, internal where it is bound to the loopback and no exposure where it is bound to every address, linked from the machine (exposes) where the machine is named.

Enforced (check): .github: cd commons/estate-endpoints && bun run verify — suite/readers.test.ts

Proved by: estate-endpoints/suite/readers.test.ts

Written in: estate-endpoints/src/logical/listening.ts

Tests: passed: suite/readers.test.ts the ports of a machine, as ss and osquery give them, are endpoints with their service, the

FR-007checkpassing

The certificate reader MUST give an asset of the kind certificate for each certificate (its subject, names, issuer, the day it ends and its key), and the files reader MUST link each endpoint that speaks over TLS to the certificate that covers its host, a wildcard name covering exactly one label.

Enforced (check): .github: cd commons/estate-endpoints && bun run verify — suite/readers.test.ts

Proved by: estate-endpoints/suite/readers.test.ts

Written in: estate-endpoints/src/logical/certificates.ts

Tests: passed: suite/readers.test.ts a certificate gives its subject, names, issuer, end day and key, a wildcard covers one lab

FR-008checkpassing

The reader of a text MUST be chosen by what is in it, and a text no reader reads MUST be a problem and no asset.

Enforced (check): .github: cd commons/estate-endpoints && bun run verify — suite/readers.test.ts

Proved by: estate-endpoints/suite/readers.test.ts

Written in: estate-endpoints/src/logical/detect.ts

Tests: passed: suite/readers.test.ts the reader is chosen by what is in the text, and a text no reader reads is a problem

FR-009checkpassing

Reading paths MUST read a file given by name (a problem where no reader reads it) and walk a folder, skipping without a word what no reader reads and the folders of tools, read the certificates of a PEM, link certificates to endpoints, and, where two files give one identity, keep the first and say so once for each file.

Enforced (check): .github: cd commons/estate-endpoints && bun run verify — suite/readers.test.ts

Proved by: estate-endpoints/suite/readers.test.ts

Written in: estate-endpoints/src/physical/files.ts

Tests: passed: suite/readers.test.ts a folder is walked, what no reader reads is skipped, a file named and unread is a problem,

Acceptance scenarios

  1. Given an OpenAPI description with a bearer scheme, When it is read, Then its endpoint has the authentication token, per FR-001.
  2. Given a manifest with an https deep link, When it is read, Then the app is linked to the endpoint, per FR-003.
  3. Given a certificate for *.example.test and an https endpoint at api.example.test, When the files are read, Then the endpoint is secured by the certificate, per FR-007.

Out of scope

  • Fetching a description, a zone or a certificate from the network, and scanning a machine for its ports: the owner makes the files.
  • Reading operations, schemas, permissions and components.

Edge cases

  • A binary property list is not read; the problem says how to convert it, per FR-004.

Assumptions

  • The ports a machine reports were reported by the machine itself, with the right to ask it (spec commons estate-query 0005-estate-query-live).

Open questions

  • None.

Key entities

  • Reader, Endpoint, Certificate.

Success criteria

SC-001success criterion

The tests of the library pass, with every asset accepted by the estate.

Review & acceptance checklist

  • [x] Every requirement is testable (MUST / MUST NOT), not aspirational
  • [x] No company fact is asserted here
  • [x] Every open item is marked, not silently decided

Cited by

Estate Endpoints: what a reader gives

Titles, headings, exports, tables, columns and requirements. Esc closes.