README
¶
🗡️ Hilt
Service for managing tenants of Ingot and their secret keys. Hilt implements the Tenant API, provides a UCAN API for retrieving proof chains for invocations into the Forge network and speaks to the Forge upload service.
Configuration
hilt serve is configured from three sources, highest precedence first:
command-line flag → HILT_* environment variable → config file → built-in
default. The config file is YAML, selected with -c/--config (default: a
config.yaml in the working directory, then /etc/hilt/config.yaml). Every key
has an env var: HILT_ + the key uppercased with . replaced by _ (e.g.
storage.postgres.dsn → HILT_STORAGE_POSTGRES_DSN). Config-file keys are the
dotted paths below (nested YAML), e.g. storage: { postgres: { dsn: ... } }.
Secrets (partner key, Vault token, AppRole secret ID) should be provided via env var or config file, not flags, to avoid exposing them in process args.
Identity (UCAN RPC service identity)
| Key | Flag | Env var | Default |
|---|---|---|---|
identity.key_file |
--identity-key-file |
HILT_IDENTITY_KEY_FILE |
(ephemeral key) |
identity.service_id |
--identity-service-id |
HILT_IDENTITY_SERVICE_ID |
(key's did:key) |
key_file is a PEM-encoded Ed25519 key; when unset an ephemeral key is generated
(its DID changes each restart). service_id optionally wraps the key with a
did:web (e.g. did:web:hilt.example.com).
Server
| Key | Flag | Env var | Default |
|---|---|---|---|
server.host |
--host |
HILT_SERVER_HOST |
127.0.0.1 |
server.port |
--port |
HILT_SERVER_PORT |
8080 |
Logging
| Key | Flag | Env var | Default |
|---|---|---|---|
log.level |
(none) | HILT_LOG_LEVEL |
info |
Storage
| Key | Flag | Env var | Default |
|---|---|---|---|
storage.type |
--storage |
HILT_STORAGE_TYPE |
postgres |
storage.postgres.dsn |
--postgres-dsn |
HILT_STORAGE_POSTGRES_DSN |
postgres://hilt:hilt@localhost:5432/hilt?sslmode=disable |
storage.postgres.max_conns |
(none) | HILT_STORAGE_POSTGRES_MAX_CONNS |
10 |
storage.postgres.min_conns |
(none) | HILT_STORAGE_POSTGRES_MIN_CONNS |
0 |
storage.postgres.skip_migrations |
--skip-migrations |
HILT_STORAGE_POSTGRES_SKIP_MIGRATIONS |
false |
storage.type is postgres or memory. Postgres keys apply when
type=postgres; migrations run on startup unless skip_migrations is set.
Vault (private-key storage)
| Key | Flag | Env var | Default |
|---|---|---|---|
vault.type |
--vault |
HILT_VAULT_TYPE |
hashicorp |
vault.hashicorp.address |
--hashicorp-address |
HILT_VAULT_HASHICORP_ADDRESS |
http://127.0.0.1:8200 |
vault.hashicorp.mount |
--hashicorp-mount |
HILT_VAULT_HASHICORP_MOUNT |
secret |
vault.hashicorp.auth_method |
--hashicorp-auth-method |
HILT_VAULT_HASHICORP_AUTH_METHOD |
approle |
vault.hashicorp.token |
--hashicorp-token |
HILT_VAULT_HASHICORP_TOKEN |
(none) — secret |
vault.hashicorp.approle.role_id |
--hashicorp-approle-role-id |
HILT_VAULT_HASHICORP_APPROLE_ROLE_ID |
(none) |
vault.hashicorp.approle.secret_id |
--hashicorp-approle-secret-id |
HILT_VAULT_HASHICORP_APPROLE_SECRET_ID |
(none) — secret |
vault.hashicorp.approle.mount |
--hashicorp-approle-mount |
HILT_VAULT_HASHICORP_APPROLE_MOUNT |
approle |
vault.type is hashicorp or memory. HashiCorp keys apply when
type=hashicorp; auth_method is approle or token (use token with
vault.hashicorp.token, or approle with the role/secret IDs).
PLC directory
| Key | Flag | Env var | Default |
|---|---|---|---|
plc.directory |
--plc-directory |
HILT_PLC_DIRECTORY |
https://plc.directory |
Tenant API auth
| Key | Flag | Env var | Default |
|---|---|---|---|
auth.partner_key |
--partner-key |
HILT_AUTH_PARTNER_KEY |
(none) — secret |
Pre-shared bearer token required on Tenant API requests.
Upload service (Sprue)
| Key | Flag | Env var | Default |
|---|---|---|---|
upload.service_id |
--upload-service-id |
HILT_UPLOAD_SERVICE_ID |
did:web:upload.forgery.network |
upload.service_url |
--upload-service-url |
HILT_UPLOAD_SERVICE_URL |
https://upload.forgery.network |
upload.product_id |
--upload-product-id |
HILT_UPLOAD_PRODUCT_ID |
did:web:hilt.forgery.network |
The Sprue service DID + HTTP endpoint Hilt calls to provision bucket space, and the product/plan DID tenants are registered under.
Directories
¶
| Path | Synopsis |
|---|---|
|
client
Package client provides the `hilt client` command tree: UCAN invocations against a running Hilt service.
|
Package client provides the `hilt client` command tree: UCAN invocations against a running Hilt service. |
|
client/admin
Package admin provides the `hilt client admin` command tree.
|
Package admin provides the `hilt client admin` command tree. |
|
client/admin/provider
Package provider provides the `hilt client admin provider` command tree.
|
Package provider provides the `hilt client admin provider` command tree. |
|
client/lib
Package lib holds shared helpers for the `hilt client` command tree.
|
Package lib holds shared helpers for the `hilt client` command tree. |
|
Package integration contains an end-to-end test harness that stands up a real Hilt in-process alongside mocks of the services it talks to — a management console (REST), the Ingot S3 gateway (UCAN RPC), and the Sprue upload service (UCAN RPC) plus a mock did:plc directory — so the REST and RPC APIs can be exercised together with the real AWS S3 SDK.
|
Package integration contains an end-to-end test harness that stands up a real Hilt in-process alongside mocks of the services it talks to — a management console (REST), the Ingot S3 gateway (UCAN RPC), and the Sprue upload service (UCAN RPC) plus a mock did:plc directory — so the REST and RPC APIs can be exercised together with the real AWS S3 SDK. |
|
internal
|
|
|
pkg
|
|
|
api
Package api defines the HTTP handlers for the Hilt tenant management API (the fil-one service orchestrator "Tenant API").
|
Package api defines the HTTP handlers for the Hilt tenant management API (the fil-one service orchestrator "Tenant API"). |
|
api/service/accesskey
Package accesskey provides the S3 access-key business logic for the REST API: creation (key-pair generation + tenant→access-key delegation issuance), listing, retrieval, and revocation.
|
Package accesskey provides the S3 access-key business logic for the REST API: creation (key-pair generation + tenant→access-key delegation issuance), listing, retrieval, and revocation. |
|
api/service/tenant
Package tenant provides the tenant-management business logic for the REST API: provisioning (did:plc key generation + PLC publication + upload-service registration), status updates, and deletion (with cascade + DID deactivation).
|
Package tenant provides the tenant-management business logic for the REST API: provisioning (did:plc key generation + PLC publication + upload-service registration), status updates, and deletion (with cascade + DID deactivation). |
|
client/management
Package management provides a REST client for Hilt's tenant and access-key management API (the handlers in pkg/api).
|
Package management provides a REST client for Hilt's tenant and access-key management API (the handlers in pkg/api). |
|
commands/admin/provider
Package provider defines the /admin/provider/* UCAN commands.
|
Package provider defines the /admin/provider/* UCAN commands. |
|
commands/admin/provider/gen
command
|
|
|
config
Package config loads hilt service configuration from a config file, environment variables (HILT_ prefix), and built-in defaults.
|
Package config loads hilt service configuration from a config file, environment variables (HILT_ prefix), and built-in defaults. |
|
fx/store/memory
Package memory wires the in-memory store implementations into the application via uber-go/fx.
|
Package memory wires the in-memory store implementations into the application via uber-go/fx. |
|
fx/store/postgres
Package postgres wires the Postgres-backed store implementations into the application via uber-go/fx.
|
Package postgres wires the Postgres-backed store implementations into the application via uber-go/fx. |
|
fx/vault/hashicorp
Package hashicorp wires the HashiCorp Vault-backed vault implementation into the application via uber-go/fx.
|
Package hashicorp wires the HashiCorp Vault-backed vault implementation into the application via uber-go/fx. |
|
fx/vault/memory
Package memory wires the in-memory vault implementation into the application via uber-go/fx.
|
Package memory wires the in-memory vault implementation into the application via uber-go/fx. |
|
migrations
Package migrations embeds the hilt Postgres migrations and exposes a runner that applies them via goose.
|
Package migrations embeds the hilt Postgres migrations and exposes a runner that applies them via goose. |
|
rpc
Package rpc implements the Hilt UCAN RPC API — the S3 commands Ingot invokes on Hilt (see the Forge S3 tenant-management RFC).
|
Package rpc implements the Hilt UCAN RPC API — the S3 commands Ingot invokes on Hilt (see the Forge S3 tenant-management RFC). |
|
rpc/service/auth
Package auth provides the request authorization service for the Hilt UCAN RPC handlers: it authenticates SigV4/SigV4a signatures, resolves the access key and tenant, and enforces the provider/region constraints shared by every S3 command.
|
Package auth provides the request authorization service for the Hilt UCAN RPC handlers: it authenticates SigV4/SigV4a signatures, resolves the access key and tenant, and enforces the provider/region constraints shared by every S3 command. |
|
rpc/service/bucket
Package bucket provides the S3 bucket business logic for the UCAN RPC API: create (authenticate + create the bucket, its bucket→tenant root delegation, and Sprue space, returning the access key's proof chains), delete (verify empty via Sprue, then tear down), list, and info (a lookup returning proof chains).
|
Package bucket provides the S3 bucket business logic for the UCAN RPC API: create (authenticate + create the bucket, its bucket→tenant root delegation, and Sprue space, returning the access key's proof chains), delete (verify empty via Sprue, then tear down), list, and info (a lookup returning proof chains). |
|
s3perm
Package s3perm maps S3 permission strings (e.g.
|
Package s3perm maps S3 permission strings (e.g. |
|
sigv4
Package sigv4 verifies AWS S3 request signatures for the two schemes the Forge S3 gateway uses: AWS4-HMAC-SHA256 (SigV4) and AWS4-ECDSA-P256-SHA256 (SigV4a).
|
Package sigv4 verifies AWS S3 request signatures for the two schemes the Forge S3 gateway uses: AWS4-HMAC-SHA256 (SigV4) and AWS4-ECDSA-P256-SHA256 (SigV4a). |
|
store/accesskey/postgres
Package postgres provides a PostgreSQL-backed implementation of accesskey.Store.
|
Package postgres provides a PostgreSQL-backed implementation of accesskey.Store. |
|
store/bucket/postgres
Package postgres provides a PostgreSQL-backed implementation of bucket.Store.
|
Package postgres provides a PostgreSQL-backed implementation of bucket.Store. |
|
store/delegation/postgres
Package postgres provides a PostgreSQL-backed implementation of delegation.Store.
|
Package postgres provides a PostgreSQL-backed implementation of delegation.Store. |
|
store/provider/postgres
Package postgres provides a PostgreSQL-backed implementation of provider.Store.
|
Package postgres provides a PostgreSQL-backed implementation of provider.Store. |
|
store/tenant/postgres
Package postgres provides a PostgreSQL-backed implementation of tenant.Store.
|
Package postgres provides a PostgreSQL-backed implementation of tenant.Store. |
|
vault
Package vault defines a KMS-agnostic interface for storing the private key material Hilt manages (tenant keys, bucket keys, S3 access keys).
|
Package vault defines a KMS-agnostic interface for storing the private key material Hilt manages (tenant keys, bucket keys, S3 access keys). |
|
vault/hashicorp
Package hashicorp provides a HashiCorp Vault (KV v2) backed implementation of vault.Vault, using github.com/hashicorp/vault-client-go.
|
Package hashicorp provides a HashiCorp Vault (KV v2) backed implementation of vault.Vault, using github.com/hashicorp/vault-client-go. |
|
vault/memory
Package memory provides an in-memory implementation of vault.Vault.
|
Package memory provides an in-memory implementation of vault.Vault. |
Click to show internal directories.
Click to hide internal directories.