8000 GitHub - ima-jin/imajin-ai: Reference implementation of the MJN Protocol. · GitHub
[go: up one dir, main page]

Skip to content
ima-jinPublic

About

Reference implementation of the MJN Protocol.

Resources

Security policy

Stars

9 stars

Watchers

1 watching

Forks

Latest commit

 

History

6,657 Commits

Folders and files

Repository files navigation

Imajin

identity and authority for AI agents.

your agents act as themselves, on your authority, and every action is signed.

Imajin is the trust layer for AI agents, for businesses putting agents in front of customers or staff, and platforms and agencies running agents for many clients. Alpha: book a demo or join the alpha as a tester, integrator or partner.

  1. Agent identity. Every agent holds its own key and proves it, with no shared passwords or API tokens. Several identities can run on one runtime, each for its own principal. The agent never impersonates the person.
  2. Delegated authority. A person grants authority explicitly and can revoke it. Risky actions wait for a named human approver. The record shows both: the person authorised it, and the agent did it.
  3. A signed record and settlement. Every action is a signed event that anyone can verify, including a third party's own agent. Cost and credit are recorded per identity, and .fair turns that into who gets paid.

Quickstart: run a node

Use Node.js, pnpm and PostgreSQL with the prerequisites in contributor setup. The setup helper prepares a local kernel database and environment, not independently owned apps.

git clone https://github.com/ima-jin/imajin-ai.git
cd imajin-ai
bash scripts/setup-local.sh
pnpm --filter @imajin/kernel dev

Open http://localhost:3000/register and save your key file. The setup helper disables the invite gate for local development only; production remains policy-gated. Deployment, deploy posture and environment configuration describe approved operator procedures. Do not deploy production with a manual git pull.

What it is

Its kernel serves Attestation · Communication · Attribution · Settlement · Discovery · Revocation, plus identity/auth, the bus, connectors, inference and media. Identity is their subject, not another primitive.

Proof of history, not proof of work: signatures and linked records establish who asserted what and under whose authority, not that every assertion is true. Actor signatures, node-witnessed actions and unsigned logs have distinct guarantees. See the proof model and whitepaper.

Revocation withdraws authority while retaining its tombstone and provenance. Erasing content or wrapped key material is not deletion of signed history. Do not infer that every propagation use case is implemented from the primitive's name.

What you can do

  • Run a kernel and compose identity, profile, connection, messaging and media services.
  • Connect an agent through the OpenClaw plugin, or build a registered app with the published SDK.
  • Act as a business or organization under live role and allowed-service checks, without confusing the human controller with the acting DID.
  • Connect provider accounts, discover usable inference models and authorize app operations without handing apps raw provider keys.
  • Manage org-held keys and member grants on /auth/connectors, where members read key status as metadata only; org owners/admins renew key expiry from /jin/vault/renew through countersigned approval.
  • Let an agent discover its own identity, usable models, inference routes and read-only MCP/HTTP connector authority through GET /infer/v1/self; operators see the same cards on /jin.
  • Send mail as an org's verified custom domain through the node's Postal server, set up under Organization settings on /jin (guide).
  • Inspect signed records, consent, grants and actionable approvals while retaining revoked and expired history.
  • Attribute content and settle supported payment flows using the owning service's contract.

The kernel guide explains these capabilities and their limits. Chat uses TLS in transit and stores plaintext at rest on the hosting node in chat.messages_v2.content. Push notifications carry the first 200 characters of the message preview. Message encryption is planned but not implemented; public key bundles do not protect current messages. See security disclosures.

Kernel vs. apps

A node operator runs the kernel, not a calendar. Apps built on Imajin have their own identities and repositories, use scoped tokens and public APIs, and never import kernel internals or read another service's tables. Follow the registered-app contract.

Workspace directory Responsibility Owned README
apps/kernel The six primitives and their shared rails Kernel
apps/broker-agent Internal Telegram broker agent surface Broker-agent
apps/corpus Internal owner-DID retrieval daemon Corpus

Independently owned apps have separate build, API and deployment contracts:

App What you compose Owned README
coffee Tips and support Coffee
dykil Surveys and responses Dykil
events Event pages, ticketing and check-in Events
learn Courses and learning Learn
links Link-in-bio pages Links
market Listings and purchases Market

Source extraction is not operational acceptance or proof of a legacy import. App schemas and data remain owned by their apps; rollback uses each app's reviewed prior deployment ref, not a removed kernel copy.

Build an app

Start from the app template and registration contract. Use auth-client for app-owned sign-in and isolated session handlers; add other published SDK packages only as needed.

npm install @ima-jin/auth-client

External consumers use @ima-jin/*; workspace imports use @imajin/*. The publish pipeline rewrites the scope and strips the private flag in the publish copy. That flag is not evidence of publication status. A registry link below is live package metadata, not a pinned compatibility promise.

Packages (SDK)

The inventory follows workspace manifests. Libraries without public npm metadata remain workspace-only; do not infer an installation command from a workspace import.

Core SDK and workspace libraries

Workspace package What it provides External availability
@imajin/auth Authentication, scoped authorization, DID helpers, signing and verification npm metadata
@imajin/auth-client App sign-in, isolated sessions, signing-key bootstrap and vault boot npm metadata
@imajin/bus Event publishing, consent brokering and ordered reactor chains Workspace-only (not on public npm)
@imajin/chat Chat components, message rendering and real-time hooks Workspace-only (not on public npm)
@imajin/cid Deterministic content identifier helpers npm metadata
@imajin/config Service routing, CORS, session configuration and route helpers npm metadata
@imajin/db Shared Postgres and Drizzle database primitives npm metadata
@imajin/dfos Identity-chain verification and content publishing Workspace-only (not on public npm)
@imajin/email Email delivery, templates and QR generation Workspace-only (not on public npm)
@imajin/emit Service-scoped operational event emission Workspace-only (not on public npm)
eslint-config-imajin Shared flat lint configuration Workspace-only (not on public npm)
@imajin/fair Attribution types, validation, manifest building and React components npm metadata
@imajin/input Composable text, voice, location and attachment inputs Workspace-only (not on public npm)
@imajin/llm Provider adapters, tool contracts and usage-cost calculation Workspace-only (not on public npm)
@imajin/logger Structured logging and request middleware npm metadata
@imajin/media Media browser, asset display and reference resolution npm metadata
@imajin/money Currency-safe amounts, signed FX snapshots and rate caching Workspace-only (not on public npm)
@imajin/notify Credential-provider-backed notification and broadcast client Workspace-only (not on public npm)
@imajin/onboard Identity onboarding gate for app pages npm metadata
@imajin/provision-bootstrap Compiled service-bootstrap provisioning entrypoint Workspace-only (not on public npm)
@imajin/tokens Shared design tokens npm metadata
@imajin/trust-graph Pod membership traversal and trust-graph queries Workspace-only (not on public npm)
@imajin/ui Shared interface components, identity management and theming npm metadata
@imajin/vault-core Vault models, integrity verification, sealing and delegation npm metadata

Plugin and harness surface

The external OpenClaw plugin and workspace envelope, provisioner, channel, inference transport, reflex guard and usage emitter have distinct responsibilities. Calling-agent inference has no shared-credential fallback; explicit non-agent host compatibility is a separate deployment mode.

Workspace package What it provides External availability
@imajin/claw-envelope Harness-neutral context envelopes and agent bootstrap Workspace-only (not on public npm)
@imajin/claw-provisioner Operator-executed provision-record and envelope runner Workspace-only (not on public npm)
@imajin/nanoclaw-imajin-channel DID-addressed chat bridge and token/usage sidecars Workspace-only (not on public npm)
@imajin/openclaw-infer-passthrough Calling-agent credential transport to kernel inference, with explicit non-agent host compatibility Workspace-only (not on public npm)
@imajin/openclaw-reflex-guard Deterministic outbound instruction checks and reflex scaffold Workspace-only (not on public npm)
@imajin/usage-emitter-claude-code External incurred-usage emitter from local session observations Workspace-only (not on public npm)

Project status

Source inventories are available through the workspace manifests above. Signed per-DID usage is exposed by the usage contract. No static identity total, unsigned inference-cost estimate or stale repository metric is asserted.

Docs / RFCs / spec

Contributing

Read AGENTS.md, canonical patterns and the PR checklist. Work in an isolated worktree. Use the agent build/lint/typecheck commands, run affected tests while iterating, and run pnpm --silent test:agent for final validation. Only the reviewed release workflow changes manifest versions.

The Release workflow pushes its branch and opens its PR with a repository-scoped GitHub App token; CI starts on pull_request. Ryan provisions the App with Contents and Pull requests read/write permissions, installed on imajin-ai only, plus the Actions variable RELEASE_APP_ID and Actions secret RELEASE_APP_PRIVATE_KEY. Keep the Actions PR-creation setting OFF; no manual PR, PAT or bypass actor. See release setup.

SonarCloud on fork PRs

The required SonarCloud CI job is a compatibility skip on forks and warns NOT SCANNED, because forks do not receive the scan token. The separate trusted follow-up runs from reviewed main after CI, with no checkout, install or execution of PR code. It authenticates the CI run and unique open PR by exact head and treats regular Git blobs and validated coverage as untrusted scan data.

Trusted settings come from the main base outside the source tree. Fork-side scanner settings, workflow edits and ignore-file changes cannot widen privileged authority or narrow the trusted scan. Malformed data, ambiguous PRs, failed/cancelled CI and stale heads fail closed.

Use sonarcloud/trusted on the exact head SHA as fork scan evidence. Its submitted analysis task must report quality gate OK. Same-repo PR and main analyses use the ordinary CI path; main has no open PR by design, and the fork follow-up skips non-PR and same-repo runs.

Gate OK alone does not establish Sonar 0: also verify zero OPEN/CONFIRMED issues and the analysis revision. A PR changing the privileged workflow cannot prove its candidate post-merge path before merge. Verify that path through an intended open fork PR after the reviewed workflow is on main; never expose the token to PR code or push a fork branch to the org to bypass the boundary.

Security

Read SECURITY.md for disclosure and implementation limits. Preserve distinctions among user signatures, node assertions and operational logs. A spec and passing source tests do not establish live deployment, federation acceptance or host custody configuration.

A note on use

A general-purpose tool can be used well or badly. The commitment is legibility, not a promise to make misuse impossible: authority, disclosure and signed actions should leave an inspectable record, including our own. A signature establishes who asserted a claim, not its truth. Soft-identity activity and unsigned logs are not user signatures.

Inspect the proof model and current security boundaries rather than treating an accountability promise as evidence that every security or revocation-propagation use case is implemented.

License

Imajin Network License, not MIT. Source-available, with notice requirements and network-participation conditions for covered commercial organizations above CAD $1 million annual revenue. The license defines conditions and exemptions; this summary does not replace it.

About

Reference implementation of the MJN Protocol.

Resources

Security policy

Stars

9 stars

Watchers

1 watching

Forks

Releases

Packages

Used by

Contributors

Languages

0