Gnosco#

Gnosco is a Rust-based escrow and badging application that integrates with the AT Protocol ecosystem. It enables communities to issue, store, and sync signed records (such as badges, awards, and other attestations) to users' ATProto repositories through a secure OAuth-based workflow.

Inspired by Smoke Signal and Lexicon Community, Gnosco provides a comprehensive framework for managing signed records in the decentralized social web, supporting both interactive web workflows and programmatic XRPC integration.

Key Features#

OAuth Authentication: Secure identity verification through ATProto handle resolution
Record Escrow: Temporary storage of signed records awaiting user approval
Automatic Syncing: Seamless writing of approved records to user repositories
Signature Verification: Cryptographic validation of record authenticity using DID documents
XRPC Integration: Programmatic API endpoint for submitting signed records
Multi-language Support: Internationalization using Mozilla Fluent
Flexible Storage: Multiple backends including PostgreSQL, SQLite, file-based, and remote HTTP sources
Dual Primary Key Design: Support for multiple issuers signing records for the same AT-URI

AT Protocol Integration#

Gnosco leverages the official atproto-* Rust crates for core AT Protocol functionality:

atproto-identity: Identity resolution and key management
atproto-oauth: OAuth authentication flows
atproto-record: Record handling and validation
atproto-client: AT Protocol client implementation
atproto-xrpcs: XRPC service integration and authorization

This ensures full compatibility and adherence to AT Protocol standards.

Configuration#

Core Settings#

EXTERNAL_BASE - External base URL for the application (required)
HTTP_PORT - HTTP server port (optional, defaults to 8080)
HTTP_STATIC_PATH - Static file directory (optional, defaults to "static")

AT Protocol Settings#

PLC_HOSTNAME - PLC directory hostname (optional, defaults to "plc.directory")
USER_AGENT - HTTP client user agent (optional)
ISSUER_DID - DID of signature issuer (required)
SIGNING_KEYS - Semicolon-separated DID method key strings (required)

Storage Settings#

RECORD_SOURCE - Escrow record data source URL or file path (required)

Record Management#

RECORD_CREATED_TIMEFRAME - Duration filter for record queries (optional)
RECORD_RETRY_ERROR - Whether to retry records with error status (optional, defaults to false)
RECORD_HTTP_TIMEOUT - HTTP timeout for record requests (optional)
RECORD_CACHE_TTL - Cache TTL for records (optional)
RECORD_MAX_RETRIES - Maximum retries for record operations (optional)

Network Settings#

DNS_NAMESERVERS - Comma-separated DNS server IPs (optional)
HTTP_CLIENT_TIMEOUT - HTTP client timeout in seconds (optional, defaults to 8)

Binaries#

Gnosco provides two main executables:

`gnosco` - Main Server Application#

The primary web server that provides OAuth authentication, record synchronization services, and XRPC API endpoints. Key capabilities:

Web Interface:

HTTP server with templated UI for user authentication
OAuth flow management for AT Protocol identity verification
Interactive record synchronization workflow

XRPC API:

POST /xrpc/community.lexicon.escrow.submitSignedRecord: Programmatic endpoint for submitting signed records
Authentication via AT Protocol OAuth with DPoP tokens
Cryptographic signature verification using DID documents

Core Services:

Record synchronization between escrow storage and user repositories
Multi-signature validation and verification
Multi-language support via Mozilla Fluent
Flexible storage backends (PostgreSQL, SQLite, file-based, remote HTTP)

`gnosco-sign` - Record Signing Tool#

Command-line utility for creating cryptographically signed AT Protocol records. Key capabilities:

Validates issuer DID identity against AT Protocol resolution
Ensures private signing key matches public key in DID document
Creates IPLD DAG-CBOR serialized signatures compatible with AT Protocol
Updates escrow records with signature metadata and status tracking
Outputs structured JSON signature data for integration workflows
Supports batch processing of multiple records

API Usage#

XRPC Endpoint#

Submit signed records programmatically via the XRPC endpoint:

curl -X POST https://your-gnosco-instance.com/xrpc/community.lexicon.escrow.submitSignedRecord \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <your-oauth-token>" \
  -d '{
    "aturi": "at://did:plc:example123/app.bsky.actor.profile/self",
    "record": {
      "signatures": [
        {
          "issuer": "did:plc:issuer456",
          "signature": "uSignatureBytes...",
          "created": "2024-01-01T00:00:00Z"
        }
      ],
      "content": { /* your record data */ }
    }
  }'

The endpoint requires:

Valid AT Protocol OAuth authentication
Proper signature verification against issuer DID documents
Valid AT-URI format for the target record

Development#

Building#

cargo build

Running the Server#

cargo run --bin gnosco

Running the Signing Tool#

cargo run --bin gnosco-sign

Testing#

cargo test

Code Quality#

cargo fmt --check
cargo clippy

Architecture#

Gnosco operates as an escrow service for signed ATProto records. The application is designed to be:

Record-type agnostic: Works with badges, events, attestations, and any signed records
Read-only for escrow data: Does not perform live signing or require signing keys
Signature verification: Validates record authenticity without needing issuer private keys
Scalable storage: Supports multiple storage backends and data sources

License#

Gnosco is open source software released under the MIT License.

Clone this repository