Skip to content

Commit 58bec68

Browse files
mastermanas805mastermanas805
committed
Merge remote-tracking branch 'origin/master' into oss/tier1-security-scanners
2 parents 1061c59 + 5a375c2 commit 58bec68

5 files changed

Lines changed: 217 additions & 0 deletions

File tree

‎CODE_OF_CONDUCT.md‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
# Code of conduct
2+
3+
InstaNode is a small, focused engineering community. We want everyone who participates — issue reporters, PR authors, reviewers, maintainers — to feel safe and respected.
4+
5+
## Expectations
6+
7+
- Be respectful in code review and issues. Critique code, not people.
8+
- Assume good intent. Ask questions before making accusations.
9+
- Keep discussions on topic. Off-topic and inflammatory threads will be closed.
10+
- No harassment, personal attacks, discriminatory language, or unwelcome sexual attention.
11+
12+
## Enforcement
13+
14+
Maintainers may close issues, lock threads, edit comments, or block accounts that violate these expectations.
15+
16+
## Reporting
17+
18+
Email security@instanode.dev to report a concern. We treat reports confidentially. We aim to respond within 72 hours.
19+
20+
## Scope
21+
22+
These expectations apply to all project spaces — issues, pull requests, discussions, and any official InstaNode communication channel — and to public spaces when someone is representing the project.
23+
24+
This policy is intentionally short; we will lengthen it as the community grows.

‎CONTRIBUTING.md‎

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,40 @@
1+
# Contributing to common
2+
3+
`common/` is shared Go code consumed by api, worker, and provisioner. Most platform feature work happens in those repos; changes here should be tightly scoped (interface additions, bug fixes, new providers).
4+
5+
## Filing issues
6+
7+
- Bugs in a specific package: open here.
8+
- Platform-wide behaviour (provisioning, billing, deploys): file in the api repo at https://github.com/InstaNode-dev/api/issues.
9+
10+
## Workflow
11+
12+
```
13+
git clone https://github.com/InstaNode-dev/common
14+
cd common
15+
go build ./...
16+
go vet ./...
17+
go test ./... -short -p 1
18+
```
19+
20+
All three must pass before opening a PR.
21+
22+
## Style
23+
24+
- Follow existing patterns in the package you're touching.
25+
- Tests next to source (`pkg/foo.go` + `pkg/foo_test.go`).
26+
- Public symbols get godoc comments.
27+
- Errors wrapped with `fmt.Errorf("context: %w", err)`.
28+
29+
## PR checklist
30+
31+
- `go build ./...` green
32+
- `go vet ./...` green
33+
- `go test ./... -short -p 1` green
34+
- New public symbol → godoc comment
35+
- New behavior → test
36+
- Commit message: short imperative subject, fuller body explaining the why
37+
38+
## License
39+
40+
MIT. By contributing, you agree your contributions are licensed under the same.

‎LICENSE‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
MIT License
2+
3+
Copyright (c) 2026 InstaNode
4+
5+
Permission is hereby granted, free of charge, to any person obtaining a copy
6+
of this software and associated documentation files (the "Software"), to deal
7+
in the Software without restriction, including without limitation the rights
8+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9+
copies of the Software, and to permit persons to whom the Software is
10+
furnished to do so, subject to the following conditions:
11+
12+
The above copyright notice and this permission notice shall be included in all
13+
copies or substantial portions of the Software.
14+
15+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21+
SOFTWARE.

‎README.md‎

Lines changed: 84 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,84 @@
1+
# common
2+
3+
Shared Go packages for the [InstaNode](https://instanode.dev) platform — the
4+
zero-friction developer infrastructure that lets agents provision databases,
5+
caches, queues, object storage, and full application deployments with a single
6+
HTTP call.
7+
8+
This repo is the **shared substrate** consumed by the three backend services:
9+
10+
- **api** — agent-facing HTTP surface (port 8080)
11+
- **worker** — River-backed background jobs (expiry, billing, propagation, email)
12+
- **provisioner** — gRPC service that creates and destroys real databases
13+
14+
Module path: `instant.dev/common` (Go 1.25+).
15+
16+
## Why a separate module?
17+
18+
Every backend service depends on the same tier definitions, the same encryption
19+
keyring, the same readiness check shape, and the same provider interfaces. We
20+
factored those out so a change to a tier limit, a new provisioner backend, or a
21+
new readiness check lands in one place and propagates to every service via a
22+
single `go mod` bump — instead of three drifting copies.
23+
24+
## Packages
25+
26+
| Package | Purpose |
27+
|---|---|
28+
| [`buildinfo`](./buildinfo) | ldflag-stamped `GitSHA` + `BuildTime` + `Version` exposed on every service's `/healthz`. Lets ops verify "is the running pod actually the commit I just pushed?" — see [InstaNode CLAUDE.md rule 14](https://instanode.dev) (Build-SHA gate). |
29+
| [`crypto`](./crypto) | AES-256-GCM keyring (multi-key with rotation), JWT signing helpers, IP fingerprint hashing (SHA256 over `/24` subnet + ASN), and base32 token generation. Fails open on decrypt errors so a key rotation doesn't break reads. |
30+
| [`logctx`](./logctx) | `slog.Handler` wrapper that injects `commit_id`, `request_id`, `team_id`, `resource_token` from `context.Context` into every structured log line. Keys are defined once here so api, worker, and provisioner emit consistent JSON. |
31+
| [`plans`](./plans) | Tier registry loaded from `plans.yaml` — the single source of truth for per-tier limits (storage MB, connection caps, deployment slots, webhook retention, etc.). Iterated by `/api/v1/capabilities` so adding a tier in `plans.yaml` + `rank.go` automatically surfaces to clients. |
32+
| [`queueprovider`](./queueprovider) | Pluggable factory + `QueueCredentialProvider` interface for NATS / RabbitMQ / Kafka / `legacyopen` backends. NATS impl mints per-tenant account JWTs + user NKeys; RabbitMQ + Kafka are portability skeletons (return `ErrNotImplemented`); `legacyopen` is the cutover shim for pre-isolation tenants. |
33+
| [`readiness`](./readiness) | Shared `Registry` + `Check` interface for deep `/readyz` endpoints. Reusable check constructors for HTTP/GET, gRPC dial, Postgres ping, Redis ping, Mongo ping, NATS ping. Per-check criticality (critical / degraded) and 10-15s cache TTL. Emits Prometheus + slog. |
34+
| [`resourcestatus`](./resourcestatus) | Shared enum for resource lifecycle states (`active`, `expired`, `deleting`, `deleted`, …) plus the expiry-warning ladder stages (6h / 2h / 1h imminent). |
35+
| [`resourcetype`](./resourcetype) | Shared enum for provisioned resource kinds (`postgres`, `redis`, `mongodb`, `queue`, `storage`, `webhook`, `deploy`, …). |
36+
| [`storageprovider`](./storageprovider) | Pluggable factory + `StorageCredentialProvider` interface for DigitalOcean Spaces / Cloudflare R2 / AWS S3 / MinIO backends. Capability-aware: each backend declares whether it supports prefix-scoped keys, bucket-scoped keys, STS temp credentials, and bucket-per-tenant — the api uses this to decide between `prefix-scoped`, `prefix-scoped-temporary`, `shared-master-key`, and `broker` modes. Live prod uses DO Spaces in `prefix-scoped` mode. |
37+
38+
## Using in a downstream service
39+
40+
```go
41+
import (
42+
"instant.dev/common/buildinfo"
43+
"instant.dev/common/logctx"
44+
"instant.dev/common/plans"
45+
"instant.dev/common/readiness"
46+
)
47+
```
48+
49+
This module is consumed via a `replace` directive in the api / worker /
50+
provisioner `go.mod` files when developing across the repo bundle locally. In
51+
prod CI, tagged releases are pulled directly.
52+
53+
## Versioning
54+
55+
`common` follows semantic versioning. **Contract changes** (a new tier in
56+
`plans.yaml`, a renamed `resourcetype`, a changed `readiness.Status` shape)
57+
must land in synchronised PRs across `common` + `api` + `worker` +
58+
`provisioner` — see the [InstaNode handoff doc](https://instanode.dev)
59+
rule 22 ("Contract changes touch all surfaces in one PR").
60+
61+
## Testing
62+
63+
```bash
64+
go test ./...
65+
```
66+
67+
Each package ships unit tests; contract tests live alongside the factory in
68+
`queueprovider/contract_test.go` and `storageprovider/contract_test.go` to
69+
verify every backend implements the interface consistently.
70+
71+
## Contributing
72+
73+
See [CONTRIBUTING.md](./CONTRIBUTING.md). Issues + PRs on this repo are
74+
welcome for shared-package bugs; platform-wide bugs (API behaviour, dashboard,
75+
billing, deploy pipeline) belong on the [api repo](https://github.com/InstaNode-dev).
76+
77+
## Security
78+
79+
See [SECURITY.md](./SECURITY.md). Report vulnerabilities privately to
80+
**security@instanode.dev** — do not open a public issue.
81+
82+
## License
83+
84+
[MIT](./LICENSE) © 2026 InstaNode.

‎SECURITY.md‎

Lines changed: 48 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,48 @@
1+
# Security Policy
2+
3+
## Reporting a vulnerability
4+
5+
If you believe you have found a security vulnerability in `common` or any
6+
downstream InstaNode service that consumes it (api, worker, provisioner,
7+
dashboard, MCP, SDK, CLI), please report it privately by emailing
8+
**security@instanode.dev**. Do not open a public GitHub issue, do not file a
9+
public PR with a fix, and do not disclose the issue on social media or in
10+
chat channels until we have had a chance to investigate and ship a fix.
11+
12+
We will acknowledge receipt within **2 business days** and aim to provide an
13+
initial assessment within **5 business days**. For critical vulnerabilities
14+
(remote code execution, credential disclosure, tenant isolation breach, billing
15+
bypass) we will ship a patch and coordinated disclosure within **30 days**.
16+
For lower-severity issues we will work with you on a reasonable timeline.
17+
18+
## Scope
19+
20+
This repository contains shared Go packages — `crypto` (AES-256-GCM keyring,
21+
JWT signing), `queueprovider` (NATS / RabbitMQ / Kafka credential issuance),
22+
`storageprovider` (DO Spaces / R2 / S3 / MinIO credential issuance),
23+
`readiness` (deep `/readyz` checks), `plans` (tier limits), `logctx`,
24+
`buildinfo`, `resourcestatus`, and `resourcetype`. A bug in any of these
25+
packages affects all three backend services, so we treat reports against this
26+
repo with the same urgency as a report against api or provisioner.
27+
28+
In-scope issues include: cryptographic weaknesses, key-handling bugs,
29+
tenant-isolation bypasses in the credential providers, secret leakage through
30+
logs or readiness output, signature-verification flaws, and denial-of-service
31+
vectors that can be triggered by a single tenant. Out of scope: bugs in
32+
upstream dependencies (please report those upstream), self-inflicted issues
33+
from running the code with development-mode secrets, and theoretical attacks
34+
that require a pre-existing compromise of the host.
35+
36+
## Safe harbor
37+
38+
We will not pursue legal action against researchers who act in good faith,
39+
who give us a reasonable opportunity to respond before disclosing publicly,
40+
who do not access or exfiltrate data beyond what is necessary to demonstrate
41+
the vulnerability, who do not perform attacks that degrade service for our
42+
users (DoS, social engineering of staff, physical attacks), and who comply
43+
with all applicable laws. We are happy to publicly credit researchers who
44+
report responsibly.
45+
46+
## Contact
47+
48+
**security@instanode.dev**

0 commit comments

Comments
 (0)