Complete backend repository handoff metadata #6
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1 @@ | ||
| * @jongan69 |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,19 @@ | ||
| --- | ||
| name: Relay or protocol bug | ||
| about: Report reproducible backend, wire-contract, storage, or deployment behavior | ||
| title: "" | ||
| labels: bug | ||
| assignees: "" | ||
| --- | ||
|
|
||
| ## Observed behavior | ||
|
|
||
| ## Expected behavior | ||
|
|
||
| ## Reproduction | ||
|
|
||
| Include the protocol version, message type, environment, and a minimal redacted request shape. Never include private keys, decrypted messages, raw identity data, or production secrets. | ||
|
|
||
| ## Evidence | ||
|
|
||
| Provide random request IDs, timestamps, safe logs, failing test names, or a minimal repository reproduction. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,8 @@ | ||
| blank_issues_enabled: false | ||
| contact_links: | ||
| - name: Security vulnerability | ||
| url: https://github.com/jongan69/OpenDating/security/advisories/new | ||
| about: Report security issues privately; never include service keys, decrypted payloads, or personal data in a public issue. | ||
| - name: Mobile application issue | ||
| url: https://github.com/jongan69/opendating-mobile/issues/new/choose | ||
| about: File screens, device behavior, and mobile-client issues in the mobile repository. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,19 @@ | ||
| --- | ||
| name: Protocol or relay proposal | ||
| about: Propose a contract, storage, reliability, privacy, or operations change | ||
| title: "" | ||
| labels: enhancement | ||
| assignees: "" | ||
| --- | ||
|
|
||
| ## Problem | ||
|
|
||
| ## Proposed outcome | ||
|
|
||
| ## Protocol and compatibility impact | ||
|
|
||
| Describe roles, request/result types, versioning, migration behavior, and the mobile coordination required. | ||
|
|
||
| ## Privacy, abuse, and operations impact | ||
|
|
||
| ## Acceptance evidence |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,12 @@ | ||
| version: 2 | ||
|
|
||
| updates: | ||
| - package-ecosystem: github-actions | ||
| directory: / | ||
| schedule: | ||
| interval: monthly | ||
| groups: | ||
| github-actions: | ||
| patterns: | ||
| - "*" | ||
| open-pull-requests-limit: 5 |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,20 @@ | ||
| ## Summary | ||
|
|
||
| ## Contract and migration impact | ||
|
|
||
| - [ ] No wire change, or the protocol version/schema/compatibility path is documented | ||
| - [ ] Migrations are additive and forward-only | ||
| - [ ] Generated protocol artifacts are current | ||
|
|
||
| ## Verification | ||
|
|
||
| - [ ] `npm run ci` passes | ||
| - [ ] `npm audit --audit-level=low` reports no unresolved vulnerability | ||
| - [ ] `npx wrangler deploy --dry-run` passes when deployment configuration changes | ||
| - [ ] Protocol package builds and `npm pack --dry-run` contains only intended files | ||
| - [ ] No secrets, private keys, raw identity keys, or decrypted payloads are logged or committed | ||
| - [ ] Mobile contract changes are coordinated with `jongan69/opendating-mobile` | ||
|
|
||
| ## Release and rollback | ||
|
|
||
| Describe deployment order, data migration, monitoring, rollback, and any feature flag or compatibility window. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,40 @@ | ||
| # Contributing to OpenDating | ||
|
|
||
| Start with `docs/opendating/BACKEND-HANDOFF.md`, then read the architecture, security, privacy, deployment, and protocol documents relevant to the change. | ||
|
|
||
| ## Setup | ||
|
|
||
| ```bash | ||
| npm ci | ||
| npm run ci | ||
| ``` | ||
|
|
||
| Node.js 22 is the supported development and CI runtime. Local Worker development also requires Wrangler and local D1 state. | ||
|
|
||
| ## Change rules | ||
|
|
||
| 1. Create a branch from protected `main` and use a pull request. | ||
| 2. Treat `packages/protocol` as the canonical client contract. Do not change request/result shapes without a compatibility and mobile-migration plan. | ||
| 3. Keep backend implementation code out of the published protocol package. | ||
| 4. Keep migrations additive and forward-only. | ||
| 5. Never commit `.dev.vars`, service private keys, data/index keys, decrypted payloads, production exports, or personal data. | ||
| 6. Do not claim a deployment is current without evidence from the exact commit. | ||
|
|
||
| ## Required checks | ||
|
|
||
| ```bash | ||
| npm run ci | ||
| npm audit --audit-level=low | ||
| npx wrangler deploy --dry-run | ||
|
|
||
| cd packages/protocol | ||
| npm ci | ||
| npm run build | ||
| npm pack --dry-run | ||
| ``` | ||
|
|
||
| Lint warnings are tracked debt; new changes should not introduce additional warnings. | ||
|
|
||
| ## Documentation | ||
|
|
||
| Update the protocol release note, handoff, deployment instructions, and mobile coordination notes whenever a change affects a service role, request route, migration, secret, binding, retention rule, or production procedure. | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,29 +1,31 @@ | ||
| # Deployment Guide | ||
|
|
||
| > **Production status:** repository CI proves the source builds; it does not prove the configured endpoint runs the same commit. Production deployment remains gated until the live Worker SHA, migrations, bindings, secret names, rollback, and restore evidence are recorded. GitHub `staging` and reviewer-gated `production` environments exist, but deployment workflows and isolated Cloudflare staging resources still need to consume them. | ||
|
|
||
| ## Profiles | ||
|
|
||
| ### Local Development | ||
|
|
||
| ```bash | ||
| npm ci | ||
| cp .env.example .env | ||
| npm run db:migrate:local | ||
| npm run dev | ||
| ``` | ||
|
Comment on lines
9
to
14
There was a problem hiding this comment. 🎯 Functional Correctness | 🟠 Major | ⚡ Quick win Provide the required local secrets before This bootstrap copies Suggested documentation change npm ci
cp .env.example .env
+# Create .dev.vars with the required local OpenDating keys.
npm run db:migrate:local
npm run dev🤖 Prompt for AI Agents |
||
|
|
||
| ### Development and limited testing | ||
|
|
||
| Cloudflare quotas and product limits change over time. Check the current official limits before sizing or enabling a market; do not treat an old limit copied into this repository as capacity evidence. | ||
|
|
||
| Configuration: | ||
| - `RELAY_INFRA_PROFILE=free` | ||
| - DB pruning at 4.0GB (target 3.5GB) | ||
| - Conservative rate limits | ||
| - Pay-to-relay disabled | ||
|
|
||
| ### Production | ||
|
|
||
| Production requires a paid capacity plan validated by load tests, storage projections, alerting, backup/restore drills, and vendor/legal signoff. The current repository does not contain that evidence. | ||
|
|
||
| Configuration: | ||
| - Higher CPU limits in wrangler.toml | ||
|
|
@@ -33,10 +35,10 @@ Configuration: | |
|
|
||
| ## Deployment Steps | ||
|
|
||
| ### 1. Provision an isolated environment | ||
|
|
||
| ```bash | ||
| wrangler d1 create opendating-relay-<environment> | ||
| ``` | ||
|
|
||
| Update `wrangler.toml` with the database ID. | ||
|
|
@@ -47,51 +49,36 @@ Update `wrangler.toml` with the database ID. | |
| npm run db:migrate:remote | ||
| ``` | ||
|
|
||
| ### 3. Set every required secret | ||
|
|
||
| ```bash | ||
| wrangler secret put OD_INDEX_KEY_V1 | ||
| wrangler secret put OD_DATA_KEY_V1 | ||
| # Repeat for each OD_<ROLE>_SERVICE_PRIVKEY in docs/SECRETS.md. | ||
| ``` | ||
|
Comment on lines
+52
to
58
There was a problem hiding this comment. 🔒 Security & Privacy | 🟠 Major | ⚡ Quick win 🧩 Analysis chain🏁 Script executed: #!/bin/bash
set -euo pipefail
echo "== files =="
git ls-files | rg '(^|/)DEPLOYMENT\.md$|(^|/)SECRETS\.md$|wrangler\.toml|package\.json|README\.md' || true
echo
echo "== deployment relevant =="
if [ -f docs/DEPLOYMENT.md ]; then
nl -ba docs/DEPLOYMENT.md | sed -n '1,110p'
fi
echo
echo "== secrets relevant =="
if [ -f docs/SECRETS.md ]; then
nl -ba docs/SECRETS.md | sed -n '1,130p'
fi
echo
echo "== wrangler configs relevant =="
files=$(git ls-files | rg 'wrangler\.toml$|wrangler\.json$|package\.json$' || true)
for f in $files; do
echo "--- $f"
nl -ba "$f" | sed -n '1,220p'
done
echo
echo "== env-related docs/code snippets =="
rg -n --hidden --glob '!node_modules/**' --glob '!dist/**' --glob '!build/**' \
'wrangler (deploy|dev|secret put|secret)|environments|environments:|production|staging|development|[[.*]]' \
docs wrangler.toml wrangler.json package.json 2>/dev/null || trueRepository: jongan69/OpenDating Length of output: 425 🏁 Script executed: #!/bin/bash
set -euo pipefail
# Examine environment and secret command semantics from local docs/config only.
python3 - <<'PY'
from pathlib import Path
import re
for p in [Path('docs/SECRETS.md'), Path('docs/DEPLOYMENT.md')]:
if not p.exists():
continue
text = p.read_text()
print(f"--- {p} secret-put occurrences ---")
for m in re.finditer(r'wrangler\s+secret\s+put\b([^\n]{0,120})', text):
start_line = text[:m.start()].count('\n') + 1
# include relevant block context lines
before = text.rfind('\n', 0, m.start())
post = text.find('\n', m.end())
print(f"L{start_line}: {text[before+1:post].strip()}")
config_paths = [Path('wrangler.toml'), Path('wrangler.json')]
for cfg in config_paths:
if not cfg.exists():
continue
text = cfg.read_text()
print(f"\n--- {cfg} environment-related lines ---")
for i,line in enumerate(text.splitlines(), 1):
if re.search(r'((production|development|staging)|name\s*=|main\s*=|wrangler)', line, re.I):
print(f"{i}: {line}")
PYRepository: jongan69/OpenDating Length of output: 733 🌐 Web query:
💡 Result: To manage secrets for specific environments in Cloudflare Workers using Wrangler, you use the --env flag with the wrangler secret put command [1][2]. The command syntax is: npx wrangler secret put --env <ENVIRONMENT_NAME> When you run this command, Wrangler will prompt you to enter the secret value securely in your terminal [1]. If you are not in an interactive terminal (such as in a CI/CD pipeline), you can pipe the value via stdin [1]: echo "your-secret-value" | npx wrangler secret put --env <ENVIRONMENT_NAME> Key details: - Environment Selection: The --env flag (or its alias -e) specifies the target environment defined in your Wrangler configuration [3][4]. - Persistence: Secrets managed via wrangler secret put are stored securely by Cloudflare and are not visible in the dashboard or Wrangler once set [5][6]. - Local Development: For local development, secrets are typically managed via.dev.vars or.env files rather than the wrangler secret put command [5][7]. You can create environment-specific files (e.g.,.dev.vars.staging) to simulate different settings locally [2][7]. For more information on managing environment-specific configurations, see the official Cloudflare Workers documentation on Environments and Secrets [5][2]. Citations:
🏁 Script executed: #!/bin/bash
set -euo pipefail
echo "== deployment relevant =="
if [ -f docs/DEPLOYMENT.md ]; then
awk '{printf "%5\t%s\n", NR, $0}' docs/DEPLOYMENT.md | sed -n '1,90p'
fi
echo
echo "== secrets relevant =="
if [ -f docs/SECRETS.md ]; then
awk '{printf "%5\t%s\n", NR, $0}' docs/SECRETS.md | sed -n '1,110p'
fi
echo
echo "== wrangler config =="
if [ -f wrangler.toml ]; then
awk '{printf "%5\t%s\n", NR, $0}' wrangler.toml
fi
echo
echo "== secret and environment references =="
awk '{printf "%5\t%s\n", NR, $@}' docs/DEPLOYMENT.md docs/SECRETS.md README.md 2>/dev/null | rg -n -i 'secret|environment|staging|production|development|--env|-e|dev\.vars|wrangler' || trueRepository: jongan69/OpenDating Length of output: 1528 🏁 Script executed: #!/bin/bash
set -euo pipefail
for f in docs/DEPLOYMENT.md docs/SECRETS.md wrangler.toml README.md; do
if [ -f "$f" ]; then
echo "===== $f ====="
sed -n '1,120p' "$f"
fi
done
echo "===== grep summary ====="
grep -RInE -i 'wrangler secret put|secret put|secret-management|development|staging|production|environment|environments|dev\.vars|--env|-e' docs README.md wrangler.toml package.json 2>/dev/null || trueRepository: jongan69/OpenDating Length of output: 22448 Scope all secret writes to the selected Cloudflare environment.
📍 Affects 2 files
🤖 Prompt for AI Agents |
||
|
|
||
| ### 4. Validate without deploying | ||
|
|
||
| ```bash | ||
| npm run build | ||
| npm run ci | ||
| npm audit --audit-level=low | ||
| npx wrangler deploy --dry-run | ||
| ``` | ||
|
|
||
| ### 5. Deploy through the approved environment | ||
|
|
||
| Production deployment must run from protected `main`, require the GitHub `production` environment approval, record the exact source SHA and migration state, and use environment-specific Wrangler configuration. Direct workstation deployment is not a production handoff procedure. | ||
|
|
||
| ### 6. Verify | ||
|
|
||
| ```bash | ||
| curl https://your-relay.example.com -H "Accept: application/nostr+json" | ||
| ``` | ||
|
|
||
| ## Wrangler Configuration | ||
|
|
||
| `wrangler.toml` is the current first-party configuration and binding inventory. Create explicit environment-specific configurations before staging deployment; never reuse production database, bucket, queue, KV, service keys, or encryption/index keys in development or staging. | ||
|
|
||
| ## Post-Deployment | ||
|
|
||
|
|
@@ -100,4 +87,7 @@ new_sqlite_classes = ["RelayWebSocket"] | |
| 3. Test EVENT publish + REQ | ||
| 4. Test NIP-42 auth | ||
| 5. Monitor Cloudflare analytics | ||
| 6. Verify OpenDating capabilities and every advertised service identity | ||
|
There was a problem hiding this comment. 🗄️ Data Integrity & Integration | 🟠 Major | ⚡ Quick win Verify the complete required service-role set. The identity loader skips missing roles and logs a warning. Therefore, “verify every advertised service identity” can pass with only a subset configured. Assert the seven required roles— 🤖 Prompt for AI Agents |
||
| 7. Verify Queue, AI, media, cache, deletion, and moderation health explicitly | ||
| 8. Record D1/R2/KV growth and queue age | ||
| 9. Exercise rollback and restore procedures before public beta | ||
Oops, something went wrong.
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win
🧩 Analysis chain
🏁 Script executed:
Repository: jongan69/OpenDating
Length of output: 743
🏁 Script executed:
Repository: jongan69/OpenDating
Length of output: 248
🏁 Script executed:
Repository: jongan69/OpenDating
Length of output: 2916
Align or label the required audit scope.
npm run cidoes not include the production audit that CI runs:npm audit --omit=dev --audit-level=high. IfRequired checksdescribes CI requirements, include the same command here; otherwise clarify thatnpm audit --audit-level=lowis a separate, stricter local check.🤖 Prompt for AI Agents