README
¶
qurl-integrations
Open-source integrations for qURL™ — Quantum URLs that make protected resources invisible by default.
qURL is built on OpenNHP (Network-infrastructure Hiding Protocol), a cryptography-driven protocol that makes servers, ports, and domains invisible to unauthorized users. A qURL wraps any resource behind a short-lived, policy-bound, cryptographically protected access token. When the token is resolved, an NHP knock grants the caller's IP temporary access — the resource literally does not exist on the network until that moment. Think of it like quantum observation: the resource only becomes visible when an authorized user observes it.
This monorepo contains qURL integrations across several surfaces — a Slack app and a CLI tool (Go), a Discord app (Node.js), and Chrome and Edge extensions for Gmail — plus shared Go libraries. A Microsoft Teams OAuth core is in progress; Zapier is planned.
Structure
apps/ Per-integration apps (released apps get independent release tracks)
slack/ Slack Secure Access Agent — /qurl slash commands (Go)
discord/ Discord app — one-time qURL links for files & locations (Node.js)
chrome-extension/ Chrome extension — Gmail file uploads as expiring qURL links (MV3)
edge-extension/ Edge extension — Gmail file uploads as expiring qURL links (MV3)
cli/ CLI — publish, resolve, and manage qURL resources by CRID (Go)
teams/ Microsoft Teams OAuth security core — no routes/SDK yet (TypeScript)
zapier/ Zapier integration (planned)
origins/ Reusable origin images for qURL Connector-protected resources
s3-static-connector/ Private S3 static site origin behind qURL Connector
shared/ Shared Go libraries used by the Go apps
client/ qURL API client
auth/ API key helpers
observability/ OpenTelemetry setup
SDKs & MCP server (separate repos)
Language SDKs and the qURL MCP server live in standalone repositories:
| Library | Install | Repo |
|---|---|---|
| Python SDK | pip install layerv-qurl |
layervai/qurl-python |
| TypeScript SDK | npm install @layervai/qurl |
layervai/qurl-typescript |
| MCP server | npx @layervai/qurl-mcp |
layervai/qurl-mcp |
Configuration
The Slack, Discord, and CLI apps connect to the qURL API:
- Endpoint — the qURL API is
https://api.layerv.ai, set viaQURL_ENDPOINT. Required for Slack; the CLI and Discord use it by default. - Authentication — an API key (
lv_live_…) inQURL_API_KEY. The CLI can also store one on the machine withqurl login(OS keyring preferred); see apps/cli/README.md.
The Chrome and Edge extensions upload to a qURL file server instead; see their Chrome README and Edge README for configuration.
Slack Connector Onboarding
Onboarding is install-first: install the qURL Slack app, run /qurl setup <email>,
then an admin runs /qurl-admin protect to expose a resource in a channel and
anyone runs /qurl get to mint a one-time link.
See apps/slack/README.md for the full command reference and onboarding walkthrough, and apps/slack/docs/operating.md for deploying and operating the Secure Access Agent.
Development
# Install pre-commit hooks
pip install pre-commit && pre-commit install
# Run all checks for the Go apps, shared/, and the repo itself (fmt, vet, lint, test)
make check
# The Node.js suites are opt-in — run the one matching your change
# (make check-node runs all five, but that is five npm installs)
make check-discord
# Run all tests
go test ./...
# Run tests for a specific app
go test ./apps/slack/...
# Build Slack Lambda
CGO_ENABLED=0 GOOS=linux GOARCH=arm64 go build -o bootstrap ./apps/slack/cmd/
Contributing
See CONTRIBUTING.md for development workflow, PR requirements, and code conventions.
Releases
This repo uses Release Please in monorepo mode.
Each released app has an independent version track. A track is earned by cutting a semver
version stream that something downstream pins to — not by merely publishing an artifact.
origins/s3-static-connector/ ships a container image but tags it only :main and :<sha>, and
shared/, apps/teams/, and apps/zapier/ ship nothing, so none of them have a track:
- Commits scoped to an app bump only that app:
feat(slack): add thread replies→slack-v0.2.0 - The CLI is the one component tagged without its prefix (
v0.2.0, notcli-v0.2.0) so OSS GoReleaser can parse the tag — see the header of.github/workflows/release-please.ymlbefore "normalizing" it - Only commits touching an app's directory trigger its release;
shared/changes ship with each app's next release - Each released app gets its own
CHANGELOG.mdonce its first release lands - CLI release assets are keyless-signed (cosign/Sigstore) and ship per-archive SPDX SBOMs — the consumer verification recipe lives in RELEASING.md
CI
Each app's workflow runs on every PR. A changes detector job inside it decides whether that
app's quality gates actually execute, and an always-reporting aggregate check — slack / required,
discord / required, chrome-extension / required, edge-extension / required,
teams / required, cli / required, s3-static-connector / required, e2e / required,
shared / required — summarizes the result. Branch protection requires those aggregates, never
the gates themselves. The full required-context set, and the rules for changing it, live in
CONTRIBUTING.md — keep this list in step with that one.
Path filtering deliberately lives in the detector rather than in on: paths:: a workflow skipped
by a trigger-level path filter never reports its checks at all, so a required aggregate would
block every PR that happens not to touch that app. The detector's filter is the source of truth
for which paths need validation, and shared-test.yml runs all Go app tests when shared/
is modified.
That pattern is itself under test. internal/ciworkflows reads every file in
.github/workflows and fails when a workflow grows a required aggregate with no registered
spec, leaves a quality gate out of required.needs, ships a verifier that treats a skipped gate
as a pass, or makes the contract check conditional. It also records every pull-request workflow's
intended branches: filter, so one recorded as deliberately narrow fails the moment it reports a
required context — including the nine aggregates, whose recorded filter is weighed against the
documented contexts rather than only against itself, so narrowing one cannot be laundered by
editing requiredWorkflowSpecs to match. This is the paths filter's trap inverted: a
workflow filtered off PRs stacked on a feature branch never registers its checks at all, and
protection guards only main, so the stacked PR reads green having run none of them
(#1183, #1185). Deleting the merged base does not recover the run: GitHub retargets the PR onto
main, but a base change arrives as the edited activity type, which no branch-filtered workflow
here takes, so the retarget re-runs nothing. The PR stalls on the check that never registered until
its next push (#1219). The package's own check — Workflow Contract — is unfiltered and reports
on every PR, because a check behind a paths filter cannot police the paths filters (#1081).
License
MIT — Copyright (c) 2025-present LayerV, Inc.
Directories
¶
| Path | Synopsis |
|---|---|
|
apps
|
|
|
cli/cmd
command
Package main is the entry point for the qurl CLI.
|
Package main is the entry point for the qurl CLI. |
|
cli/cmd/sandbox-matched-cohort-authority
command
Command sandbox-matched-cohort-authority is the sandbox-only fixed canary provisioning and rotation worker.
|
Command sandbox-matched-cohort-authority is the sandbox-only fixed canary provisioning and rotation worker. |
|
cli/cmd/sandbox-matched-cohort-lifecycle
command
Command sandbox-matched-cohort-lifecycle runs the protected sandbox-only fixed-canary lifecycle and recovery-first outcomes.
|
Command sandbox-matched-cohort-lifecycle runs the protected sandbox-only fixed-canary lifecycle and recovery-first outcomes. |
|
cli/internal/api
Package qurlapi is the CLI's single seam to the qURL platform.
|
Package qurlapi is the CLI's single seam to the qURL platform. |
|
cli/internal/apitest
Package apitest is the mock qURL API used by the CLI's contract tests.
|
Package apitest is the mock qURL API used by the CLI's contract tests. |
|
cli/internal/auth
Package auth resolves the qURL API credential for the CLI.
|
Package auth resolves the qURL API credential for the CLI. |
|
cli/internal/clitest
Package clitest holds the golden-file helper shared by the CLI's output tests.
|
Package clitest holds the golden-file helper shared by the CLI's output tests. |
|
cli/internal/config
Package config loads qURL CLI configuration files and resolves setting precedence.
|
Package config loads qURL CLI configuration files and resolves setting precedence. |
|
cli/internal/connector/agent
Package agent orchestrates the CLI qURL Connector's native agent lifecycle around the qurl-go SDK: first-time enrollment with a one-shot token, warm re-open of the persisted device identity, and the operator-gated assignment refresh that self-heals a stale Hub binding.
|
Package agent orchestrates the CLI qURL Connector's native agent lifecycle around the qurl-go SDK: first-time enrollment with a one-shot token, warm re-open of the persisted device identity, and the operator-gated assignment refresh that self-heals a stale Hub binding. |
|
cli/internal/connector/frpgen
Package frpgen generates the single-route FRP client configuration for the CLI qURL Connector: the managed HTTP route shape the tunnel server authorizes, expressed as a neutral, fully typed config model plus a deterministic TOML rendering.
|
Package frpgen generates the single-route FRP client configuration for the CLI qURL Connector: the managed HTTP route shape the tunnel server authorizes, expressed as a neutral, fully typed config model plus a deterministic TOML rendering. |
|
cli/internal/connector/hub
Package hub resolves and validates the NHP Hub trust bootstrap for the CLI's qURL Connector: which Hub endpoint to talk to, and which pinned server public key proves it is the real one.
|
Package hub resolves and validates the NHP Hub trust bootstrap for the CLI's qURL Connector: which Hub endpoint to talk to, and which pinned server public key proves it is the real one. |
|
cli/internal/connector/knock
Package knock is the per-cycle NHP admission seam between the qURL Connector supervisor and qurl-go's native UDP knock runtime.
|
Package knock is the per-cycle NHP admission seam between the qURL Connector supervisor and qurl-go's native UDP knock runtime. |
|
cli/internal/connector/replica
Package replica normalizes the per-replica discriminator string that makes this process unique among co-deployed replicas of the same qURL Connector.
|
Package replica normalizes the per-replica discriminator string that makes this process unique among co-deployed replicas of the same qURL Connector. |
|
cli/internal/connector/state
Package state owns the CLI qURL Connector's on-disk native agent state: where the state directory lives, the qurl-go file-backed agent state envelope opened inside it, and the assignment-refresh marker breadcrumb written next to it.
|
Package state owns the CLI qURL Connector's on-disk native agent state: where the state directory lives, the qurl-go file-backed agent state envelope opened inside it, and the assignment-refresh marker breadcrumb written next to it. |
|
cli/internal/connector/supervisor
Package supervisor is the qURL Connector's knock-then-login serve loop: it wraps the FRP client service with a managed-restart cycle in which every dial is preceded by a fresh NHP knock against the assigned admission controller.
|
Package supervisor is the qURL Connector's knock-then-login serve loop: it wraps the FRP client service with a managed-restart cycle in which every dial is preceded by a fresh NHP knock against the assigned admission controller. |
|
cli/internal/consume
Package consume turns a verified resolve answer into the thing the user asked for: the resource open in their browser, or its bytes on disk.
|
Package consume turns a verified resolve answer into the thing the user asked for: the resource open in their browser, or its bytes on disk. |
|
cli/internal/cridux
Package cridux is the warn-only UX layer over the SDK's crid package.
|
Package cridux is the warn-only UX layer over the SDK's crid package. |
|
cli/internal/exitcode
Package exitcode is the CLI's single exit-code authority.
|
Package exitcode is the CLI's single exit-code authority. |
|
cli/internal/matchedcohort
Package matchedcohort owns the environment-neutral fixed-canary authority used by the sandbox matched-cohort rollout.
|
Package matchedcohort owns the environment-neutral fixed-canary authority used by the sandbox matched-cohort rollout. |
|
cli/internal/output
Package output owns every byte the qURL CLI writes.
|
Package output owns every byte the qURL CLI writes. |
|
slack/cmd
command
Package main is the HTTP entrypoint for the Slack integration.
|
Package main is the HTTP entrypoint for the Slack integration. |
|
slack/cmd/slack-dm-smoke
command
Command slack-dm-smoke runs an operator-triggered Slack DM delivery smoke.
|
Command slack-dm-smoke runs an operator-triggered Slack DM delivery smoke. |
|
slack/cmd/slack-history-upload-smoke
command
The Slack Web API transport for this command: one read method, one retry, and the response envelope every read shares.
|
The Slack Web API transport for this command: one read method, one retry, and the response envelope every read shares. |
|
slack/cmd/statecrawl
command
Package main implements statecrawl, an operational reconciler for the qURL Slack bot's channel_policies DynamoDB table.
|
Package main implements statecrawl, an operational reconciler for the qURL Slack bot's channel_policies DynamoDB table. |
|
slack/internal
Package internal contains Slack-specific handler logic.
|
Package internal contains Slack-specific handler logic. |
|
slack/internal/agent
Package agent implements the qURL Secure Access Agent conversation mode: a natural-language translation + preview layer that sits on top of the deterministic slash-command operations.
|
Package agent implements the qURL Secure Access Agent conversation mode: a natural-language translation + preview layer that sits on top of the deterministic slash-command operations. |
|
slack/internal/connectorimage
Package connectorimage validates the qURL Connector image reference used in customer-facing install snippets.
|
Package connectorimage validates the qURL Connector image reference used in customer-facing install snippets. |
|
slack/internal/nethost
Package nethost holds host-name predicates shared by the Slack app's request handlers, its startup configuration checks, and the operator smoke commands.
|
Package nethost holds host-name predicates shared by the Slack app's request handlers, its startup configuration checks, and the operator smoke commands. |
|
slack/internal/oauth
Package oauth implements per-workspace Slack OAuth handlers (/oauth/qurl/start and /oauth/qurl/callback).
|
Package oauth implements per-workspace Slack OAuth handlers (/oauth/qurl/start and /oauth/qurl/callback). |
|
slack/internal/slackaudit
Package slackaudit emits machine-filterable audit records for Slack runtime dependencies.
|
Package slackaudit emits machine-filterable audit records for Slack runtime dependencies. |
|
slack/internal/slackdata
Package slackdata is the DDB-direct replacement for the old admin_client.go HTTP wrapper around qurl-service `/internal/v1/admin/*`.
|
Package slackdata is the DDB-direct replacement for the old admin_client.go HTTP wrapper around qurl-service `/internal/v1/admin/*`. |
|
slack/internal/slackinstall
Package slackinstall implements the Slack app OAuth installation flow.
|
Package slackinstall implements the Slack app OAuth installation flow. |
|
slack/internal/slacksmoke
Package slacksmoke holds the Slack Web API hardening that the operator-triggered smoke commands under apps/slack/cmd share.
|
Package slacksmoke holds the Slack Web API hardening that the operator-triggered smoke commands under apps/slack/cmd share. |
|
internal
|
|
|
ttlcache
Package ttlcache provides a small keyed TTL cache with per-key singleflight fills and generation-guarded invalidation.
|
Package ttlcache provides a small keyed TTL cache with per-key singleflight fills and generation-guarded invalidation. |
|
shared
|
|
|
auth
Package auth provides authentication helpers for qURL integrations.
|
Package auth provides authentication helpers for qURL integrations. |
|
client
Package client provides a Go client for the qURL API.
|
Package client provides a Go client for the qURL API. |
|
observability
Package observability provides telemetry setup and log redaction for qURL integrations.
|
Package observability provides telemetry setup and log redaction for qURL integrations. |