{"id":51037211,"url":"https://github.com/ao3575911/dark-swan","last_synced_at":"2026-06-22T07:30:57.327Z","repository":{"id":358166701,"uuid":"1240114044","full_name":"ao3575911/dark-swan","owner":"ao3575911","description":"Decentralized identity and symbolic anonymization protocol — Ed25519 signing, rotating pseudonyms, and local registry for private verifiable identities.","archived":false,"fork":false,"pushed_at":"2026-05-16T02:09:06.000Z","size":24,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-16T04:13:56.919Z","etag":null,"topics":["anonymization","cryptography","decentralized","ed25519","identity","privacy","pseudonym","python"],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ao3575911.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-15T19:31:10.000Z","updated_at":"2026-05-16T02:09:09.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/ao3575911/dark-swan","commit_stats":null,"previous_names":["ao3575911/dark-swan"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/ao3575911/dark-swan","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ao3575911%2Fdark-swan","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ao3575911%2Fdark-swan/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ao3575911%2Fdark-swan/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ao3575911%2Fdark-swan/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ao3575911","download_url":"https://codeload.github.com/ao3575911/dark-swan/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ao3575911%2Fdark-swan/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34639701,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-22T02:00:06.391Z","response_time":106,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["anonymization","cryptography","decentralized","ed25519","identity","privacy","pseudonym","python"],"created_at":"2026-06-22T07:30:56.140Z","updated_at":"2026-06-22T07:30:57.319Z","avatar_url":"https://github.com/ao3575911.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# dark-swan\n\nUser-sovereign pseudonymous identity for builders who do not want identity owned by states, platforms, or vendors.  \nEvery identity has a canonical `did:ds:\u003cfingerprint\u003e` derived from its public key, plus a 4-letter symbolic short name — verifiable, portable, and daily-rotating.\n\n\u003e \"Self-issued identity. Portable proofs. No permission layer.\"\n\n---\n\n## Install\n\n```bash\npip install -e .\n```\n\nThat's it. The `ds` command is now available globally.\n\n**Dependencies:** `cryptography\u003e=41` (standard Ed25519 + encrypted PEM key files). No other runtime deps.  \n**Optional:** `gdk9` — install only if you want deeper symbolic/DCG path analysis in `ds profile`.\n\n---\n\n## Quick start\n\n```bash\n# Create a legacy deterministic identity\nds generate \"your secret seed\"\n\n# Preferred: create a random encrypted key file\nds keygen --output identity.pem --passphrase \"strong passphrase\"\nds generate-key identity.pem --passphrase \"strong passphrase\"\n\n# Sign a message\nds sign \"your secret seed\" \"hello world\"\n\n# Verify a signature (no seed needed)\nds verify \u003cpubkey_b64\u003e \"hello world\" \u003csignature\u003e\n\n# Register in local registry\nds publish \"your secret seed\"\n\n# Look up by DID, symbolic short name, or handle\nds lookup FWEM\nds lookup ds-QVWK\n```\n\n---\n\n## Commands\n\n| Command | Description |\n|---------|-------------|\n| `generate \u003cseed\u003e` | Legacy deterministic seed identity — DID, symbolic short name, handle, symbolic profile |\n| `keygen` | Create a random Ed25519 key file, encrypted by default |\n| `generate-key \u003cfile\u003e` | Show DID/profile info from a PEM key file |\n| `sign \u003cseed\u003e \u003cmsg\u003e` | Sign a message with legacy seed mode; outputs signature + pubkey |\n| `sign-key \u003cfile\u003e \u003cmsg\u003e` | Sign a message with a key file |\n| `verify \u003cpubkey\u003e \u003cmsg\u003e \u003csig\u003e` | Verify without a seed; re-derives symbolic ID |\n| `publish \u003cseed\u003e` | Register legacy seed identity in the local registry |\n| `publish-key \u003cfile\u003e` | Register key-file identity in the local registry |\n| `publish \u003cseed\u003e --overwrite` | Replace an existing registry record |\n| `lookup \u003cid\\|handle\u003e` | Resolve a symbolic ID or `ds-XXXX` handle |\n| `search` | Filter registry by `--dr`, `--class`, or `--energy-range` |\n| `profile \u003cword\u003e` | Symbolic breakdown of any 4-letter word |\n| `proof create \u003cseed\u003e` | Create a signed portable proof card |\n| `proof verify \u003cfile\u003e` | Verify a proof card |\n| `proof card \u003cfile\u003e` | Display a formatted proof card |\n\n**Global flags** (before the subcommand):\n\n```\n--registry FILE   Path to registry JSON  (default: registry.json)\n--no-color        Disable ANSI output\n--json            Also emit JSON alongside human output\n```\n\n---\n\n## How identities work\n\n```\nseed\n └→ SHA-256(seed)\n     └→ Ed25519 private key\n         └→ public key  (32 bytes raw)\n             └→ SHA-256(pubkey)\n                 └→ first 4 bytes → A-Z  →  symbolic_id  e.g. KLNI\n                                              │\n                                    SHA3-256(id + epoch_day) → handle  ds-QVWK\n```\n\nThe canonical DID is derived from the **public key only** using the first 16 bytes of `SHA-256(pubkey)` as 32 lowercase hex characters. The symbolic short name (`KLNI`, `FWEM`, …) is also derived from the public key and remains the human-readable short label. Anyone with your public key can independently verify both — no seed required.\n\n**Ephemeral handles** (`ds-XXXX`) rotate each UTC day.\n\n---\n\n## Symbolic metrics\n\nThe 4-letter short name is not the canonical identity key — the DID is. The symbolic layer is an optional UX/indexing layer that makes identities easier to recognize, discuss, and search. Each letter carries a symmetry class that determines its energy contribution:\n\n| Class | Color | Letters | Energy rule |\n|-------|-------|---------|-------------|\n| idempotent | cyan | A H I M O T U V W X Y | `pos` |\n| biphasic | yellow | B C D E K | `sin(pos)` |\n| involutive | magenta | N S Z | `1/pos` |\n| asymmetric | red | F G J L P Q R | `pos + 1` |\n\n**Digital root** (DR 1–9): A1Z26 letter sum reduced to a single digit (9 if divisible by 9).  \n**SymPhi energy**: sum of each letter's energy value under its class rule.\n\nRecords can be indexed by DR and total energy for registry search. Keep this if you want human/memetic navigation; ignore it if you want a pure cryptographic DID workflow.\n\n---\n\n## Registry search\n\n```bash\nds search --dr 7                        # all identities with digital root 7\nds search --class asymmetric            # dominant class filter\nds search --energy-range 10,50          # SymPhi energy band\nds search                               # list all\n```\n\n---\n\n## Key files\n\nFor production-style identities, prefer random key files over human seed strings:\n\n```bash\nds keygen --output identity.pem --passphrase \"strong passphrase\"\nds sign-key identity.pem \"hello world\" --passphrase \"strong passphrase\"\nds publish-key identity.pem --passphrase \"strong passphrase\"\nds proof create-key identity.pem --passphrase \"strong passphrase\" --claim \"I control this identity\"\n```\n\n`ds generate \u003cseed\u003e` remains available for deterministic demos and compatibility, but raw `SHA-256(seed)` is not recommended for high-value identities.\n\n## Python API\n\n```python\nfrom ds_protocol_core import DSIdentity, verify_message, pubkey_to_id\n\n# Generate an identity\nidentity = DSIdentity(\"your secret seed\")\nprint(identity.symbolic_id)          # e.g. \"KLNI\"\nprint(identity.ephemeral_handle())   # e.g. \"ds-QVWK\" — rotates daily\nprint(identity.public_key_b64())     # base64url-encoded Ed25519 public key\n\n# Sign a message\nsig = identity.sign(\"hello world\")\n\n# Verify with only the public key (no seed needed)\npubkey = identity.public_key_b64()\nok = verify_message(pubkey, \"hello world\", sig)  # True\nsid = pubkey_to_id(pubkey)                        # re-derives symbolic ID\n```\n\nSee `examples/` for complete workflows including registry use.\n\n---\n\n## Proof cards\n\nCreate a portable, signed identity proof:\n\n```bash\nds proof create \"your secret seed\" --claim \"I built dark-swan\"\n# → proof.json\n\nds proof verify proof.json\n# → ✓ valid\n\nds proof card proof.json\n# → formatted proof display\n```\n\nA proof card is a signed JSON object containing your canonical DID, symbolic ID, handle, claim, expiry, public key, and Ed25519 signature. Verification checks the signature and confirms that DID + symbol match the embedded public key. Anyone can verify it with only the public key — no seed, no registry lookup required.\n\n---\n\n## Optional symbolic integration\n\nInstall `gdk9` alongside dark-swan only if you want:\n\n- DCG path analysis in `ds profile`\n- Homotopy equivalence checks between symbolic IDs\n- Full SymPhi energy model\n\n```bash\npip install -e ../gdk9   # or wherever your gdk9 lives\n```\n\n---\n\n## Project layout\n\n```\nds_gdk9.py           Symbolic metrics bridge (standalone, no gdk9 dep)\nds_protocol_core.py  DSIdentity — keypair, signing, symbolic ID derivation\nds_registry.py       Persistent JSON registry with GDk9-aware search\nds_proof.py          Proof cards — create, sign, and verify portable proofs\nds_cli.py            CLI — generate, sign, verify, publish, lookup, search, profile, proof\ndocs/\n  protocol_design.md  Full protocol specification\n  philosophy.md       Project purpose and design rationale\n  roadmap.md          Planned milestones\nexamples/            Runnable Python examples\ntests/               124 unit tests\n```\n\n---\n\n## Roadmap\n\nSee [docs/roadmap.md](docs/roadmap.md) for the full plan. Short version:\n\n| Version | Theme |\n|---------|-------|\n| v0.2.1 | Hardening — registry fixes, CLI validation, proof cards, full CI |\n| v0.3 | DID / fingerprint rollout, optional KDF, SQLite registry |\n| v0.4 | Proof cards v2 — QR codes, claim chains |\n| v0.5 | Decentralized registry / transparency log |\n\n---\n\n## License\n\nMIT — © 2025 Adam Grange (@beathovn)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fao3575911%2Fdark-swan","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fao3575911%2Fdark-swan","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fao3575911%2Fdark-swan/lists"}