The commerce edge: ERPNext serves, Medusa consumes
Archived, superseded by Frappe is the platform and Medusa is not adopted as infrastructure.
The commerce edge: ERPNext serves, Medusa consumes
Section titled “The commerce edge: ERPNext serves, Medusa consumes”★ RE-SCOPED BY OWNER RULING 2026-08-16: READ THIS FIRST
Section titled “★ RE-SCOPED BY OWNER RULING 2026-08-16: READ THIS FIRST”The owed work in §5 and §7 of this document is NO LONGER OURS.
docs/decisions/2026-08-16-frappe-over-medusa.mdrules that Frappe/ERPNext is the platform for everything and that Medusa is not adopted as infrastructure, not for DesiBox, the SHC portal, the marketplace, BitSpur or FlyingFoxLabs. The Medusa↔ERPNext bridge therefore leaves our backlog and becomes a customer-funded feature.What that ruling does not do: it does not deprecate
apps/standalone/medusa. That package remains a catalogue app we sell, edge and all. The ruling governs what we run, not what we ship.§5 is superseded twice over. Once by reality: the sidecar rung was abandoned for compiled-in Medusa Subscribers (push) plus the provider-side
frappe_medusabench app (pull); the canonical account of that move is inapps/standalone/medusa/erpnext.plug.yamlandcompose.yaml. And once by the ruling, which reassigns who pays for whatever remains. Read §5 as a historical contract, not as a task list. The paths in the table below are also pre-reorganisation: the consumer now lives atapps/standalone/medusa/and the provider atapps/flagship/frappe/.Everything else here (§0’s measured facts, §1’s direction argument, §3’s mint/revoke design, §4’s auth model) still stands and is still the reason the shipped edge is shaped the way it is.
Status: design document + landed phase 1. Written 2026-08-09 alongside the code it describes:
| file | half |
|---|---|
apps/platform/frappe/erpnext.socket.yaml | provider: the erpnext singleton socket, its bench gate, its mint and its revoke |
apps/business/medusa/erpnext.plug.yaml | consumer: the bind, the narrow attach, the embodiment argument |
apps/business/medusa/medusa-erpnext-arm.job.yaml | consumer: the proof and the vault seal |
apps/business/medusa/compose.yaml | consumer: the (double-gated) sync sidecar |
apps/business/medusa/{vars,app}.yaml | consumer: the knobs and their types |
apps/business/medusa/tests/tests.bats | 17 static guards |
The question it answers: how does a shop stop being a second copy of the business?
0. Ground truth: measured facts this design leans on
Section titled “0. Ground truth: measured facts this design leans on”Everything in this section was read out of source or measured, not recalled. Anything not in this section that reads like a fact is a claim.
G1. Medusa v2 has no outbound webhooks and no runtime plugin loading.
The supported extension point is a Subscriber under src/subscribers/*.ts,
compiled into the application by medusa build; plugins are build-time node
modules. Already recorded in apps/business/medusa/vars.yaml’s
images.medusa note, which is also why this app ships its own image and its
own Dockerfile.
G2. Frappe is multi-tenant BY HOST HEADER, and there is no default_site
fallback in the WSGI path. frappe/app.py:183 (version-15):
site = _site or request.headers.get("X-Frappe-Site-Name") or get_site_name(request.host)frappe.init(site=site, sites_path=_sites_path, force=True)
if not (frappe.local.conf and frappe.local.conf.db_name): # site does not exist raise NotFoundapps/platform/frappe/compose.yaml records this as measured on this estate
(2026-08-04, hq.corp.bitspur.com against site hq.bitspur.com) and names
X-Frappe-Site-Name as one of the two mechanisms proven to work. This is
the single most load-bearing fact in the whole edge. An overlay alias is
never a site name, so a consumer dialling internalUrl without that header
gets a bare 404 for every request, including a perfectly authenticated one,
and a 404 reads as a wrong path, so it gets debugged as a wrong path.
G3. Frappe’s API-key pair is readable back after creation.
frappe/auth.py:700-720, validate_api_key_secret, is frappe’s own
authenticator and it reads the stored secret on every request:
doc_secret = get_decrypted_password(doctype, docname, fieldname="api_secret", raise_exception=False)if doc_secret and api_secret == doc_secret:It also filters the user on {"api_key": api_key, "enabled": True} (:708),
which is what makes “disable the user” a complete revocation.
G4. The auth header is Authorization: token <api_key>:<api_secret>.
frappe/auth.py:683-690: auth_type.lower() == "token" splits on :;
"basic" base64-decodes the same pair. A malformed pair is swallowed
(except (AttributeError, TypeError, ValueError): pass, :693) and the
request continues as Guest, so “authenticated as Guest” is a distinct,
detectable failure and the arm probe checks for it by name.
G5. frappe.core.doctype.user.user.generate_keys is a ROTATOR.
user.py:1326-1342: it assigns a fresh api_secret unconditionally (:1339)
while preserving api_key, and carries frappe.only_for("System Manager")
(:1332). Calling it on every deploy rotates the credential on every deploy.
G6. User.add_roles / remove_roles call self.save() themselves
(user.py:617, :625). append_roles (:608) does not. And user_type is
DERIVED, not set: set_system_user (:307) resolves it to "System User" if self.has_desk_access() else "Website User". A role set with no desk access
silently produces a Website User whose ERPNext reads all 403.
G7. ERPNext role names, read out of erpnext version-15 doctype JSON.
| DocType | roles present |
|---|---|
Item | Accounts User, Desk User, Item Manager, Maintenance User, Manufacturing User, Purchase User, Sales User, Stock Manager, Stock User |
Bin | Purchase Manager, Purchase User, Sales Manager, Sales User, Stock Manager, Stock User |
Sales Order | Accounts User, Maintenance User, Sales Manager, Sales User, Stock User |
Item Price | Purchase Master Manager, Sales Master Manager, and nothing else |
The last row is the sharp one: ERPNext offers no read-only role over pricing in version-15, so “let Medusa read prices” and “let Medusa rewrite your price lists” are the same grant.
G8. bench --site <site> list-apps reports the apps installed ON THE SITE.
frappe/commands/site.py:534 reads the Installed Applications single and
falls back to frappe.get_installed_apps(); :522-526 pads the name column to
the widest app name. That is the right question: an app present in apps/ but
never install-app-ed on the site has no doctypes there.
G9. A minted value reaches the consumer’s post-hook render and NOTHING
ELSE. ce modules/app/install_runner.go: the compose file is rendered at
~:860-930 from integrationsCtx; RunSocketIntegrationJobs runs at :1461;
MergeJobMintedValues(integrationsCtx, …) at :1473. The compose render is
~600 lines and one whole phase earlier. This is the constraint that put
sonarqube’s GitLab binding and gitlab’s Sentry seal in their apps’ hooks, and
it puts ours there too.
G10. The hook seal is MINT-ONCE. ce modules/app/hook_actions_run.go
defines two channels: ::shc-hook:var: (plaintext, lands verbatim in
vars.yaml + manifest var_overrides) and ::shc-hook:secret: (routed through
the vault, only a ref+vault://…?autogen persisted). hook_minted_vars.go’s
sealHookSecret is documented “Idempotent (mint-once): a re-install reuses
the value sealed by the first”, and a failed seal fails closed; it is
never downgraded to a plaintext write.
G11. No sync image exists. Searched 2026-08-09:
github.com/aerele/medusa_integration: real (MIT, 31 stars, last push 2026-07-30), and not this. It is a Frappe bench app, i.e. it runs on the provider side; itsMedusa Configurationdoctype storesadmin_email+admin_passwordand exchanges them for a Bearer token, i.e. ERPNext holds a Medusa administrator’s password; and it is not a general connector; the repo adds ~25 bespoke storefront DocTypes (Homepage Banner,Best Deals,Email OTP,Medusa Wishlist,Product Details Banner,Product Collection…) and customises ~20 core ERPNext doctypes (Item,Sales Order,Sales Invoice,Quotation,Customer,Lead…). That is one integrator’s client build, not a mechanism. Evaluated and rejected.gitlab.com/bitspur/community/medusa-erpnext-syncappears in web-search results and does not resolve: the unauthenticated GitLab API answers404 Project Not Found. The on-box token at~/.tokens/gitlabreturns401, so a private-project check could not be completed; see §7. It is treated as non-existent and nothing pins it.
1. Direction: ERPNext serves, Medusa consumes
Section titled “1. Direction: ERPNext serves, Medusa consumes”The test is not which app matters more. It is which side holds the record the other is a projection of.
Items, stock, prices, customers, receivables and the general ledger exist whether or not a shop does. ERPNext is the book. A Medusa product is a merchandising view of an ERPNext Item: it carries storefront-only facts (handle, collection membership, SEO copy, the variant option matrix) that ERPNext has no opinion about, and it is reconstructible from the Item if lost. An ERPNext Item is not reconstructible from a Medusa product; losing it loses valuation, the purchase history, the tax template and the ledger lineage.
The direction also falls out of the socket rules mechanically, which is the stronger argument because it does not depend on taste:
A provider is the side that can mint a per-consumer, scoped, revocable credential.
ERPNext can: a Frappe User with an API-key pair is a first-class identity with
roles, an enabled flag, and an audit trail (G3, G7). Medusa v2 cannot; its
admin identity is an email/password row in the user table, there are no API
tokens, no service accounts and no per-integration roles. An edge pointing the
other way would have to hand ERPNext a shared Medusa administrator password,
which is exactly what the one existing open-source connector does (G11) and
exactly why this design does not use it.
Naming. erpnext, the bare app name, because this is a tier-2 app-dialect
contract: the wire is Frappe’s REST dialect and the payload is ERPNext’s record
model. Not erp, an outcome name with a dozen unrelated faces (Odoo,
Dolibarr, Tryton, NetSuite) and nothing a consumer could write against. Not
frappe: that is the framework, and a bare Frappe bench has none of Item,
Bin, Sales Order, Sales Invoice, Payment Entry. A future
framework-level socket (Users, Files, the OAuth server) would take the frappe
stem and would be a different, narrower thing.
2. Embodiment: a compose sidecar, consumer-side
Section titled “2. Embodiment: a compose sidecar, consumer-side”The ladder is native loop > plugin vApp > fork-carried > compose sidecar. Each rung above the sidecar is unavailable or refused, for a reason that belongs to the software rather than to taste:
Native loop: unavailable. Medusa has no outbound webhooks and no way to register an external listener at runtime (G1). There is no configuration that makes a stock image sync anything.
Plugin vApp: unavailable. Medusa’s plugins are build-time node modules
resolved by medusa build (G1). There is nothing for a vApp to install into a
running Medusa; “installing” one means rebuilding the image, which is not what
a vdeployment does. (Contrast frappe and wordpress, whose app/plugin models
genuinely admit runtime addition, and note that even on frappe the house
ruling is that plug mechanisms are image-owned, baked and vars-activated,
never vapp:.)
Fork-carried: available, and deliberately refused. This app’s image is
ours, built from the Dockerfile in its own directory, so compiling the sync
in as a Subscriber is genuinely on the table and is the rung the ladder would
otherwise pick. It is refused on coupling:
- the sync would ship on Medusa’s clock; every sync bugfix becomes a Medusa image rebuild and a full-stack redeploy;
- a sync crash-loop becomes a crash-loop of the process serving checkout;
- most of the work has no event to subscribe to. Catalogue and stock are a pull on a timer; only the order push is event-shaped.
A rung is not worth taking when it buys nothing the rung below lacks and costs the blast radius of the checkout path.
Compose sidecar: taken. The bridge is its own container in Medusa’s stack, on Medusa’s own clock, restartable and diagnosable alone. The bridge is the broker, this is an edge broker, and per house doctrine edge-brokers run consumer-side. Identity-brokers would be provider-adjacent; this is not one.
The order push lives in the sidecar too, even though that half is event-shaped, because splitting the halves across two runtimes (a compiled-in Subscriber pushing, a sidecar pulling) would put one edge’s state in two places on two release clocks. The sidecar polls Medusa’s Admin API for orders. The cost, stated plainly: push latency is one poll interval, not sub-second. For an order landing in an ERP that is correct; for a payment-capture webhook it would not be, and payment capture is not in scope.
3. The provider half: erpnext.socket.yaml
Section titled “3. The provider half: erpnext.socket.yaml”3.1 The vdeployment gate (jobs.discovery)
Section titled “3.1 The vdeployment gate (jobs.discovery)”frappe the app and erpnext the bench app are on separate clocks. The image
pin can carry erpnext (today’s does), a factory core flavour does not, and in
VAPP mode, the default, the bench volume is seeded ONCE and an image bump is
a documented silent no-op for apps/ (vars.yaml’s images.frappe note).
So “the frappe stack is up” says nothing about whether the doctypes this
socket’s entire contract is made of exist.
Without the gate the failure is invisible in the worst way: the bind succeeds,
the mint succeeds, the consumer authenticates successfully, and then every
/api/resource/Item answers 404, which reads as a wrong path, not a missing
app.
The job therefore:
- resolves the site:
vars.siteNamewhen it exists on disk, else the bench’s only site, else refuses. (The fallback is not paranoia: both live production benches are restored ones, and a restored site keeps its archive’s name whilevars.siteNamegoes on naming whatever the install was given.) - runs
bench --site <site> list-appsand requires an anchored^erpnext(G8); - on failure, prints the apps that are installed and the per-mode fix:
activateApps=erpnextwhen erpnext is on the bench but not on the site; an erpnext-carrying image whenbakeApps=true; and forbakeApps=falsethe explicit warning that an image bump will NOT changeapps/.
3.2 The mint (jobs.integration)
Section titled “3.2 The mint (jobs.integration)”One dedicated Frappe User per consumer: shc-<label>@integration.invalid.
.invalid is RFC 2606 reserved, so the account can never send or receive mail;
send_welcome_email = 0 and flags.no_welcome_mail suppress the attempt.
label is charset-gated to [A-Za-z0-9][A-Za-z0-9_-]*; it is both the
revocation handle and the local-part of an email address, and two consumers
sharing it are one identity that revoke each other.
Roles are reconciled, not merely added (dropping a role from the plug must
actually take the capability away), through append_roles + a single save()
rather than add_roles/remove_roles, which save on every call (G6). A role
that does not exist on the site is a refusal, not a silent drop, because a
silently-dropped role produces exactly the same under-privileged user as
granting none.
The credential is created-if-absent and otherwise republished verbatim.
This is the one deliberate divergence from the gitlab socket, and it is
forced from both ends:
- provider end: unlike a GitLab PAT, a Frappe
api_secretis readable back (G3). Stability is available here and was not there. - consumer end: the consumer must SEAL the value to get it into compose (G9), and that seal is mint-once (G10). A rotating secret would diverge from its own seal on deploy two and stay diverged forever, with the sidecar presenting a credential the provider had already replaced.
generate_keys is therefore not used at all: it is a rotator (G5).
Everything is read back before it is published: enabled flag, api_key,
the secret read the way frappe’s own authenticator reads it, user_type == "System User" (G6), and the exact role set. Coordinates and verdicts are
printed; values never are.
3.3 The revoke (jobs.unintegration)
Section titled “3.3 The revoke (jobs.unintegration)”It disables and de-keys; it does not delete. A Frappe User is referenced by
owner and modified_by on every document it ever touched, plus Version,
Comment and Activity Log rows; deleting it either fails link validation or
rewrites history. Disabling is what actually closes the door; frappe’s
authenticator filters enabled=True (G3), and the key pair is cleared so the
value the consumer may still hold in its vault matches nothing.
No lifetime: managed: that gate marks jobs that DESTROY a resource and is
frozen closed today, so a gated job never runs. Releasing a credential this
socket minted is not a destroy.
4. The auth model, end to end
Section titled “4. The auth model, end to end” frappe stack medusa stack┌───────────────────────┐ ┌────────────────────────────┐│ jobs.integration │ │ ││ grant-erpnext-api-key│ │ ││ ├ create-if-absent │ │ ││ ├ read back │ │ ││ └ ::shc-connection- │──── mint-and-return ─┼─▶ post_install hook render ││ value::apiSecret │ (ce G9) │ medusa-erpnext-arm │└───────────────────────┘ │ ├ probe 1: authn │ ▲ │ ├ probe 2: authz │ │ Authorization: token k:s │ └ ::shc-hook:secret:: │ │ X-Frappe-Site-Name: <site> (G2) │ │ │ │ │ ▼ vault (G10) │ └────────────────────────────────────┼──── vars.erpnext.apiSecret │ │ │ │ │ ▼ NEXT deploy │ │ medusa-erpnext-sync │ └────────────────────────────┘The proof is two requests, not one. frappe.auth.get_logged_user is
@frappe.whitelist() (frappe/auth.py:433) and answers for any
authenticated identity, roles or not, so it proves authentication and its
return value proves which identity, but a green probe there would still be
green for a credential that 403s on every business read. The second request
reads /api/resource/Item and is what proves authorization. A 403 prints the
role fix; a 404 prints the site-header diagnosis (G2); “authenticated as
Guest” prints the swallowed-header diagnosis (G4).
The sidecar is armed on the second deploy. The mint reaches the hook render
and never the compose render (G9), so the credential gets into compose only by
way of the vault seal, which the next render reads. This is the identical
caveat gitlab’s Sentry seal carries (“reaches GITLAB_OMNIBUS_CONFIG on the
NEXT deploy”) and it is a property of the channel, not of this app. It is also
why the probe matters so much: the probe is the only thing that runs on
deploy one, and it is what turns “the edge is bound” from a claim into a
fact.
Divergence fails loudly here, where gitlab’s seal exits 0. Same shape,
different cost: a stale Sentry DSN means error reports go nowhere (degraded); a
stale ERPNext key means the sidecar authenticates with nothing: no stock, no
prices, no orders, and a storefront quietly selling from a frozen catalogue.
That earns an X500908HKFAIL (logged loudly, stack stays up) rather than a
line in a job log nobody reads.
The asymmetry, named. One end of this edge has a first-class revocable
identity; the other has an administrator password (MEDUSA_ADMIN_EMAIL /
MEDUSA_ADMIN_PASSWORD). That is Medusa’s shape, not ours; see §7 for what is
owed.
5. The sync contract: the program nobody has written
Section titled “5. The sync contract: the program nobody has written”vars.erpnext.syncImage is empty and the medusa-erpnext-sync service does
not render without it (G11). This section is what an image must implement to
be nameable there. It is a contract, not a description of something that
exists.
5.1 Non-negotiables
Section titled “5.1 Non-negotiables”- Send
X-Frappe-Site-Name: <ERPNEXT_SITE>on every ERPNext request. Without it every call 404s, authenticated or not (G2). If the bridge does one thing right, this is it. - Idle, never crash, on an empty credential.
ERPNEXT_API_KEY/ERPNEXT_API_SECRETare empty on the deploy that first binds the edge (§4). The bridge must log once per interval and keep the container up, so the post-install hook has something to exec into and sorestart: unless-stoppedis not a crash-loop. - Refuse to start on a missing
ERPNEXT_COMPANYorERPNEXT_WAREHOUSE. Do not guess. A wrong Company posts to the wrong ledger; a stock figure summed across warehouses is not sellable stock. - One serialised loop. Do not interleave a stock write with an order write
against the same Item.
x-shc-scale.max: 1enforces one replica for the same reason. - Never write into ERPNext what ERPNext owns. The bridge creates sales documents and customers; it does not edit Items, prices, or stock levels.
5.2 Pull: ERPNext → Medusa
Section titled “5.2 Pull: ERPNext → Medusa”| step | ERPNext read | Medusa write |
|---|---|---|
| catalogue | GET /api/resource/Item filtered disabled=0, is_sales_item=1, and item_group=ERPNEXT_ITEM_GROUP when set | upsert Product, keyed by Item.name |
| variants | Item Variant / Item.variant_of | Product variants, keyed by the child Item.name |
| stock | GET /api/resource/Bin filtered warehouse=ERPNEXT_WAREHOUSE | absolute inventory level per variant |
| price | GET /api/resource/Item Price filtered price_list=ERPNEXT_PRICE_LIST, needs Sales Master Manager (G7); skip the whole step when ERPNEXT_PRICE_LIST is empty | variant price |
- The join key is
Item.name, carried on the Medusa side inexternal_id/metadata. Never the SKU: an ERPNextitem_codeis editable and a Medusa handle is user-facing. - Stock is absolute, not a delta. ERPNext’s
Bin.actual_qtyis the truth and the bridge overwrites. This is why ordering matters and why one replica is enforced. actual_qty, not a sum. Reserved-quantity semantics (reserved_qty,projected_qty) are a policy choice; expose it as a var before changing it, do not fold it in silently.- Paginate.
limit_start/limit_page_length; hold one page at a time (the 512M limit is sized for that). - Use
modifiedas the cursor. ERPNext stamps it on every doctype; filter["modified", ">", <last-success>]and keep the watermark in the bridge’s own Medusa metadata, so the bridge holds no durable state of its own; which is what lets it have no volume and lets a disconnect be a no-op.
5.3 Push: Medusa → ERPNext
Section titled “5.3 Push: Medusa → ERPNext”| trigger | Medusa read | ERPNext write |
|---|---|---|
| new order | GET /admin/orders since watermark | Customer (create-if-absent, needs ERPNEXT_CUSTOMER_GROUP + ERPNEXT_TERRITORY), then Sales Order |
| capture / refund | order payment collections | Payment Entry against the Sales Order |
- Idempotency key: the Medusa order id, written into a field on the Sales Order and checked before insert. A duplicated push is the failure mode that costs real money.
ERPNEXT_SUBMIT_SALES_ORDERSdefaults to false: orders land as DRAFTS. Deliberately timid: a submitted Sales Order reserves stock and is only reversible by cancel+amend, so an unattended sync that submits turns every storefront mistake into an accounting correction.- Never delete. A cancelled Medusa order becomes a cancellation document, not a deletion.
5.4 Operational contract
Section titled “5.4 Operational contract”- Log a one-line summary per cycle: items seen / updated, stock updated, orders pushed, errors. It is the only observability this edge has.
- Exit non-zero only on a configuration error (missing Company/Warehouse). A transport failure is a retry, not a death; the ERP being down must not take the storefront’s stack with it.
- Expose a health endpoint.
compose.yamldeliberately declares no healthcheck today because the image is operator-named and a probe invented here would report a state nobody measured; when a real image exists, its probe belongs in that file.
6. Phasing
Section titled “6. Phasing”Phase 1: LANDED with this change. The credential edge, proven.
shc install medusa --stack shop -i postgres=pg -i erpnext=<frappe-stack>:
the socket gates on erpnext-on-bench, mints the scoped Frappe User, the arm
hook proves both authentication and authorization from inside medusa’s stack
and seals the pair. No sidecar renders. This is a coherent resting state, not
a half-built one; the estate has a verified, revocable ERPNext edge with
nothing running on it, and every later phase starts from a credential that has
already been proven rather than assumed.
Phase 2: the read-only pull. Build a bridge to §5.2 only, name it in
vars.erpnext.syncImage, redeploy. Read-only against ERPNext, so the blast
radius is Medusa’s catalogue. Ship this alone and let it run before writing a
line of §5.3.
Phase 3: the order push. §5.3 with submitSalesOrders: false. Drafts
only; a human submits. Promote to submitted only after the idempotency key has
been observed to hold under a real duplicate.
Phase 4: payments. Payment Entry reconciliation. Out of scope here and
deliberately last: it is the half where a bug is a ledger correction.
7. What is owed, and every unknown named
Section titled “7. What is owed, and every unknown named”Owed on the provider side (outside this change’s surface, another agent is live-probing that package):
apps/platform/frappe/tests/tests.batshas no guards for any of this. What it needs, in order: (1)list-appsnames erpnext on the pinned image; (2)jobs.discoveryFAILS on a bench without erpnext; (3) the mint createsshc-<label>@integration.invalidreading back enabled,System User, and exactly the granted roles; (4) a second run republishes the identical key pair, the stability property the consumer’s mint-once seal depends on, and the one most likely to regress; (5) an authenticatedfrappe.auth.get_logged_userwithX-Frappe-Site-Namereturns the minted user and the same request without that header returns 404 (G2 asserted as a fact, not a comment); (6) the revoke leaves the user present, disabled and de-keyed, and is a clean no-op on a second run.apps/platform/frappe/{vars,app}.yamldeclare nopublicUrl. The socket therefore publishes emptyurl/apiUrl(guarded with| default(''), so it renders rather than errors) and every consumer uses the internal pair. It cannot be derived fromvars.siteName: on both live production benches the public hostname and the site name differ, which is the symlink casecompose.yamldocuments. DeclaringpublicUrl@urlthere is a small, clean change that this surface could not make.
Owed on the consumer side:
- A dedicated Medusa user for the bridge. Today it authenticates as the
seeded administrator. A
medusa userseeded by an init job does not narrow the capability (every Medusa admin is equally powerful) but it makes revocation possible without locking the operator out. Medusa v2 offers nothing better; there are no API tokens and no roles. - A healthcheck on the sidecar, once an image exists (§5.4).
- A live end-to-end test. Every guard shipped here is static, deliberately: driving this edge needs a frappe stack with erpnext activated, which is a multi-gigabyte second stack and a several-minute boot, and hanging it off medusa’s suite would make every medusa change wait on it. It belongs in the provider’s suite.
Unknowns, stated rather than papered over:
- No sync image exists and none is being written by this change. Phase 1 ships without one on purpose.
gitlab.com/bitspur/community/medusa-erpnext-synccould not be definitively ruled out. The unauthenticated GitLab API says404 Project Not Found; GitLab returns 404 for private projects to unauthenticated callers, and the on-box token at~/.tokens/gitlabis expired (401), so “absent” and “private” are indistinguishable from here. Someone with a live token should check before anyone writes §5 from scratch. Nothing in this change pins it.- Nothing here has run against a live ERPNext. The
erpnext-bitspurMCP endpoint failed DNS resolution (getaddrinfo ENOTFOUND hq.bitspur.com) during this work, so every ERPNext claim above is sourced from erpnext / frappeversion-15source rather than from a live instance. The mint’s Python is syntax-checked and every shell body passessh -n; neither has been executed inside a frappe container. That is the single largest gap between this document and reality. - The
Desk Userrole appears inItem’s permission list on version-15 and is not in the default grant. If a v15 bench turns out to require it for desk access, the mint’suser_type != "System User"read-back is what will catch it, loudly, at bind time, naming the field. That is by design, but it has not been observed. - Multi-site benches are refused, not supported. This socket is per-site
because the site name is the address (G2). A bench serving two sites needs
vars.siteNameto name the one it serves; serving both would need two sockets, which the current socket model has no shape for. erpnext.__version__is read best-effort and never fatal. If the attribute moves the version publishes empty and nothing breaks.
8. Alternatives rejected, with reasons
Section titled “8. Alternatives rejected, with reasons”| alternative | why not |
|---|---|
Adopt aerele/medusa_integration | Inverts the credential direction (ERPNext holds a Medusa admin password), runs provider-side as a bench app, and carries ~25 bespoke storefront DocTypes + ~20 core-doctype customisations, one integrator’s client build, not a mechanism (G11). |
| Compile the sync into our Medusa image as a Subscriber | Available, and refused on coupling: sync fixes become image rebuilds, a sync crash-loop becomes a checkout crash-loop, and the pull half has no event to subscribe to (§2). |
Name the socket erp | Outcome name with a dozen unrelated faces; no consumer could write against it (§1). |
Name the socket frappe | That is the framework; a bare Frappe bench has none of the doctypes this contract is made of (§1). |
generate_keys for the mint | It is a rotator (G5), and a rotating secret diverges permanently from the consumer’s mint-once seal (G10, §3.2). |
| Revoke-then-mint, like the gitlab socket | Same reason. The property that forces gitlab’s choice (a PAT’s plaintext is unrecoverable) does not hold for frappe (G3). |
| Delete the minted User on disconnect | It owns document history through owner/modified_by on everything it touched; deleting either fails link validation or rewrites history (§3.3). |
Put the bind in the plug’s jobs.post_deployment | It renders from the statically rendered socket data, where the credential is the empty string the socket publishes on purpose. It would seal two empty strings and report success (G9). |
Pin medusa or valkey in the plug’s services: | A pinned service becomes a DNS alias on the provider’s network; valkey would shadow frappe’s own valkey for every frappe service resolving the bare name. |
| Publish the ERPNext admin password / mysql credentials on the socket | A socket data: block renders once per provider with no per-consumer variation to gate on; anything there goes to every consumer. |
Include Sales Master Manager in the default grant | It is the only role that can read Item Price on version-15 and it is read+write over pricing masters (G7). The decision belongs to the operator, in the open. |
| Give the sidecar a healthcheck now | The image is operator-named; a probe invented here would report a state nobody measured. |