From 831851182458a232c09782a5a9a78cf0550080e2 Mon Sep 17 00:00:00 2001 From: Steve-Mcl Date: Wed, 28 Oct 2026 20:55:26 +0000 Subject: [PATCH 1/4] Add application scoped project link topics and targets API Broker ACLs for application scoped project link broadcasts (ff/v1//a//p//out/...) and for direct messages and call responses to application owned devices (ff/v1//p/dev:/in|res/...). New GET /api/v1/teams/:teamId/project-link/targets for project and device tokens: the team's applications with their instances and application owned devices, plus the caller's own identity. Ids and names only, hidden from the API docs. The nodes use it to detect platform support. Also: - checkDeviceIsAssigned honours deviceOwnerType - a device can reply to a call from an HA instance (res-) --- docs/user/projectnodes.md | 43 ++-- forge/comms/aclManager.js | 42 ++++ forge/db/models/Project.js | 11 + forge/ee/lib/projectComms/index.js | 57 ++++- forge/ee/routes/index.js | 1 + forge/ee/routes/projectLink/index.js | 146 +++++++++++++ test/unit/forge/comms/authRoutes_spec.js | 204 ++++++++++++++++++ .../forge/ee/routes/projectLink/index_spec.js | 142 ++++++++++++ 8 files changed, 630 insertions(+), 16 deletions(-) create mode 100644 forge/ee/routes/projectLink/index.js create mode 100644 test/unit/forge/ee/routes/projectLink/index_spec.js diff --git a/docs/user/projectnodes.md b/docs/user/projectnodes.md index 1747759536..4055afe13f 100644 --- a/docs/user/projectnodes.md +++ b/docs/user/projectnodes.md @@ -1,7 +1,7 @@ --- navTitle: FlowFuse Project Nodes meta: - description: Send messages and call flows between Node-RED instances in a team with the Project In, Out and Call nodes, and the limits for remote instances. + description: Send messages and call flows between Node-RED instances and remote instances in a team or application with the Project In, Out and Call nodes. --- # FlowFuse Project Nodes @@ -12,8 +12,7 @@ instances in a team. The nodes act in a similar way to the Node-RED Link nodes, but by allowing the links to extend between different instances, they open up a wide range of -possibilities. Remote instances can take part too, with the limitations described -below. +possibilities. Remote instances can take part too. For example, a single Node-RED instance may contain a set of utility flows that you want to reuse in other instances. Rather than copy the flows around, the @@ -53,18 +52,38 @@ and then wait for a response, with a built-in timeout if it doesn't arrive. The response is sent back using a Project Out node configured to respond to the call node. +### Applications + +The list of targets and sources offered by the nodes is grouped by application, +and can be filtered to a single application. It contains the hosted instances in +your team and the remote instances assigned to an application. + +Broadcast messages are sent on one of two channels: + + - **Team broadcast** - received by any instance or remote instance in the team + whose `Project In` node listens for team broadcasts. This is the default. + - **Application broadcast** - only received by instances and remote instances in + the same application whose `Project In` node listens for application broadcasts. + Instances outside the application cannot send or receive these messages. + +The channels are separate. A `Project In` node listening for team broadcasts does +not receive application broadcasts, even from an instance in the same application. + +Received messages include `msg.projectLink.applicationId`, the application of the +sender, and for broadcasts `msg.projectLink.scope`, the channel it was sent on. + ### Limitations -**Only hosted instances can be addressed directly.** The list of targets and sources -offered by the nodes is the hosted instances in your team. This applies to the -`Project Out` node when sending to a specific instance, the `Project In` node when -listening to a specific source, and the `Project Call` node's target. +**Remote instances assigned to an instance are reached through that instance.** They +share the identity of the instance they are assigned to, so they are not listed +separately. A message or call sent to the instance is also received by its remote +instances that are listening on the same topic. -**A remote instance can send, but cannot be sent to.** Flows on a remote instance can -use `Project Out` and `Project Call` to reach a hosted instance, and can receive -broadcasts. They cannot be named as a target, so shared logic being called by others -has to live on a hosted instance. A remote instance assigned to an application cannot -receive direct messages at all, and can only listen for broadcasts. +**Calls need the target to be up.** The `Project Call` node waits for the default +timeout of 30 seconds, then logs an error that can be caught with a Catch node. The +target instance must be running and have a `Project In` node listening on the same +topic. Because every call travels through the platform's broker, logic called this +way is unavailable to a caller whose connection to the platform is down. **Calls need the target to be up.** The `Project Call` node waits for the default timeout of 30 seconds, then logs an error that can be caught with a Catch node. The diff --git a/forge/comms/aclManager.js b/forge/comms/aclManager.js index 88ff6dd098..585d40cc38 100644 --- a/forge/comms/aclManager.js +++ b/forge/comms/aclManager.js @@ -73,6 +73,9 @@ module.exports = function (app) { // check to see if the device is assigned to something? const assignedTo = await app.db.models.Device.getOwnerTypeAndId(ids[2]) if (assignedTo && assignedTo.ownerType && assignedTo.ownerId) { + if (acl.deviceOwnerType && acl.deviceOwnerType !== assignedTo.ownerType) { + return false // rule does not apply to this type of device owner + } return true } return false @@ -132,6 +135,45 @@ module.exports = function (app) { return false } }, + checkClientInApplication: async function (requestParts, ids, acl) { + // requestParts = [ _ , , , ] + // ids = [ 'project', , ] or [ 'device', , ] + + // Do the simple team id check + if (requestParts[1] !== ids[1]) { + return false + } + let applicationId + let sourceId + try { + if (ids[0] === 'project') { + applicationId = await app.db.models.Project.getProjectApplicationId(ids[2]) + sourceId = ids[2] + } else if (ids[0] === 'device') { + const assignedTo = await app.db.models.Device.getOwnerTypeAndId(ids[2]) + if (assignedTo?.ownerType === 'instance') { + // An instance owned device is part of its instance's application + // and broadcasts using its instance id + applicationId = await app.db.models.Project.getProjectApplicationId(assignedTo.ownerId) + sourceId = assignedTo.ownerId + } else if (assignedTo?.ownerType === 'application') { + applicationId = assignedTo.ownerId + sourceId = `dev:${ids[2]}` + } + } + } catch (err) { + // Any error likely means an id isn't a valid uuid - which + // postgres with throw over, unlike sqlite that returns no results. + return false + } + if (!applicationId || applicationId !== requestParts[2]) { + return false // not a member of this application + } + if (acl.checkSource && requestParts[3] !== sourceId) { + return false // can only publish as itself + } + return true + }, checkTeamUserSession: async function (requestParts, usernameParts) { // requestParts = [ fullTopic , [, ] ] - v1 // requestParts = [ fullTopic , , , ] - v2 (MCP) diff --git a/forge/db/models/Project.js b/forge/db/models/Project.js index deae239481..f343f116cb 100644 --- a/forge/db/models/Project.js +++ b/forge/db/models/Project.js @@ -727,6 +727,17 @@ module.exports = { return project.TeamId } }, + getProjectApplicationId: async (id) => { + const project = await this.findOne({ + where: { id }, + attributes: [ + 'ApplicationId' + ] + }) + if (project && project.ApplicationId) { + return M.Application.encodeHashid(project.ApplicationId) + } + }, generateCredentialSecret () { return crypto.randomBytes(32).toString('hex') }, diff --git a/forge/ee/lib/projectComms/index.js b/forge/ee/lib/projectComms/index.js index 91154d4845..56f9bfea62 100644 --- a/forge/ee/lib/projectComms/index.js +++ b/forge/ee/lib/projectComms/index.js @@ -51,6 +51,20 @@ module.exports.init = function (app) { 'pub', { topic: /^ff\/v1\/([^/]+)\/p\/([^/]+)\/out\/[^/]+($|\/.*$)/, verify: 'checkTeamAndObjectIds' } ) + // Receive application scoped broadcasts from members of this project's application + // - ff/v1//a//p/+/out/+/# + app.comms.aclManager.addACL( + 'project', + 'sub', + { topic: /^ff\/v1\/([^/]+)\/a\/([^/]+)\/p\/([^/]+)\/out\/[^/]+($|\/.*$)/, verify: 'checkClientInApplication', shared: true } + ) + // Send application scoped broadcast messages + // - ff/v1//a//p//out/+/# + app.comms.aclManager.addACL( + 'project', + 'pub', + { topic: /^ff\/v1\/([^/]+)\/a\/([^/]+)\/p\/([^/]+)\/out\/[^/]+($|\/.*$)/, verify: 'checkClientInApplication', checkSource: true } + ) // Device ACL @@ -61,12 +75,19 @@ module.exports.init = function (app) { 'sub', { topic: /^ff\/v1\/([^/]+)\/p\/([^/]+)\/out\/[^/]+($|\/.*$)/, verify: 'checkDeviceIsAssigned' } ) - // Receive messages sent to this device + // Receive messages sent to this device (instance owned) // - ff/v1//p//in/+/# app.comms.aclManager.addACL( 'device', 'sub', - { topic: /^ff\/v1\/([^/]+)\/p\/([^/]+)\/in\/[^/]+($|\/.*$)$/, verify: 'checkDeviceCanAccessProject' } + { topic: /^ff\/v1\/([^/]+)\/p\/(?!dev:)([^/]+)\/in\/[^/]+($|\/.*$)$/, verify: 'checkDeviceCanAccessProject' } + ) + // Receive messages sent to this device (app owned) + // - ff/v1//p/dev:/in/+/# + app.comms.aclManager.addACL( + 'device', + 'sub', + { topic: /^ff\/v1\/([^/]+)\/p\/dev:([^/]+)\/in\/[^/]+($|\/.*$)$/, verify: 'checkDeviceIsAssigned', deviceOwnerType: 'application' } ) // Receive link-call response messages sent to this device (instance owned) // - ff/v1//p//res/+/# @@ -89,6 +110,13 @@ module.exports.init = function (app) { 'pub', { topic: /^ff\/v1\/([^/]+)\/p\/(?!dev:)([^/]+)\/in\/[^/]+($|\/.*$)/, verify: 'checkDeviceCanAccessProject', deviceOwnerType: 'instance' } ) + // Send message to specific app owned device + // - ff/v1//p/dev:/in/+/# + app.comms.aclManager.addACL( + 'device', + 'pub', + { topic: /^ff\/v1\/([^/]+)\/p\/dev:([^/]+)\/in\/[^/]+($|\/.*$)/, verify: 'checkDeviceIsAssigned' } + ) // Send broadcast messages (from instance owned devices in the team) // - ff/v1//p//out/+/# app.comms.aclManager.addACL( @@ -104,11 +132,32 @@ module.exports.init = function (app) { { topic: /^ff\/v1\/([^/]+)\/p\/dev:([^/]+)\/out\/[^/]+($|\/.*$)/, verify: 'checkDeviceIsAssigned', deviceOwnerType: 'application' } ) // Send link-call response messages back to source instance - // - ff/v1//p/+/res/+/# + // - ff/v1//p/+/res[-id]/+/# + app.comms.aclManager.addACL( + 'device', + 'pub', + { topic: /^ff\/v1\/([^/]+)\/p\/(?!dev:)([^/]+)\/res(?:-[^/]+)?\/[^/]+($|\/.*$)/, verify: 'checkDeviceCanAccessProject', deviceOwnerType: 'instance' } + ) + // Send link-call response messages back to source app owned device + // - ff/v1//p/dev:/res/+/# + app.comms.aclManager.addACL( + 'device', + 'pub', + { topic: /^ff\/v1\/([^/]+)\/p\/dev:([^/]+)\/res\/[^/]+($|\/.*$)/, verify: 'checkDeviceIsAssigned' } + ) + // Receive application scoped broadcasts from members of this device's application + // - ff/v1//a//p/+/out/+/# + app.comms.aclManager.addACL( + 'device', + 'sub', + { topic: /^ff\/v1\/([^/]+)\/a\/([^/]+)\/p\/([^/]+)\/out\/[^/]+($|\/.*$)/, verify: 'checkClientInApplication' } + ) + // Send application scoped broadcast messages + // - ff/v1//a//p//out/+/# app.comms.aclManager.addACL( 'device', 'pub', - { topic: /^ff\/v1\/([^/]+)\/p\/(?!dev:)([^/]+)\/res\/[^/]+($|\/.*$)/, verify: 'checkDeviceCanAccessProject', deviceOwnerType: 'instance' } + { topic: /^ff\/v1\/([^/]+)\/a\/([^/]+)\/p\/([^/]+)\/out\/[^/]+($|\/.*$)/, verify: 'checkClientInApplication', checkSource: true } ) // Team Broker ACLS - pub/sub to common topic space diff --git a/forge/ee/routes/index.js b/forge/ee/routes/index.js index 2f2b6a1f05..0635abd0aa 100644 --- a/forge/ee/routes/index.js +++ b/forge/ee/routes/index.js @@ -34,6 +34,7 @@ module.exports = async function (app) { await app.register(require('./pipeline'), { prefix: '/api/v1', logLevel: app.config.logging.http }) await app.register(require('./pipeline/teamPipelines.js'), { prefix: '/api/v1/teams/:teamId/pipelines', logLevel: app.config.logging.http }) await app.register(require('./deviceEditor'), { prefix: '/api/v1/devices/:deviceId/editor', logLevel: app.config.logging.http }) + await app.register(require('./projectLink'), { prefix: '/api/v1/teams/:teamId/project-link', logLevel: app.config.logging.http }) await app.register(require('./flowBlueprints'), { prefix: '/api/v1/flow-blueprints', logLevel: app.config.logging.http }) diff --git a/forge/ee/routes/projectLink/index.js b/forge/ee/routes/projectLink/index.js new file mode 100644 index 0000000000..c662e76f8b --- /dev/null +++ b/forge/ee/routes/projectLink/index.js @@ -0,0 +1,146 @@ +const { Op } = require('sequelize') + +const teamShared = require('../../../routes/api/shared/team.js') + +/** + * Routes used by the Project Link nodes (@flowfuse/nr-project-nodes) + * @param {import('../../forge').ForgeApplication} app - forge application + * @namespace projectLink + * @memberof forge.ee + */ +module.exports = async function (app) { + app.addHook('preHandler', teamShared.defaultPreHandler.bind(null, app)) + + // not registered with addSchema so it stays out of the swagger docs + const targetListSchema = { + type: 'array', + items: { + type: 'object', + properties: { + id: { type: 'string' }, + name: { type: 'string' } + }, + additionalProperties: false + } + } + + /** + * Get the applications in a team along with the hosted instances and + * application owned devices that Project Link nodes can communicate with. + * Only available to project and device tokens. + * /api/v1/teams/:teamId/project-link/targets + */ + app.get('/targets', { + preHandler: app.needsPermission('team:projects:list'), + schema: { + hide: true, + params: { + type: 'object', + properties: { + teamId: { type: 'string' } + } + }, + response: { + 200: { + type: 'object', + properties: { + self: { + type: 'object', + nullable: true, + properties: { + id: { type: 'string' }, + applicationId: { type: 'string' } + }, + additionalProperties: false + }, + applications: { + type: 'array', + items: { + type: 'object', + properties: { + id: { type: 'string' }, + name: { type: 'string' }, + instances: targetListSchema, + devices: targetListSchema + }, + additionalProperties: false + } + } + }, + additionalProperties: false + }, + '4xx': { + $ref: 'APIError' + } + } + } + }, async (request, reply) => { + if (!app.config.features.enabled('projectComms')) { + return reply.code(404).send({ code: 'not_found', error: 'Not Found' }) + } + const ownerType = request.session.ownerType + if (ownerType !== 'project' && ownerType !== 'device') { + return reply.code(403).send({ code: 'unauthorized', error: 'unauthorized' }) + } + const TeamId = app.db.models.Team.decodeHashid(request.params.teamId) + + const [applications, instances, devices] = await Promise.all([ + app.db.models.Application.findAll({ + where: { TeamId }, + attributes: ['id', 'name'], + order: [['name', 'ASC']] + }), + app.db.models.Project.findAll({ + where: { TeamId }, + attributes: ['id', 'name', 'ApplicationId'], + order: [['name', 'ASC']] + }), + app.db.models.Device.findAll({ + // application owned devices only - instance owned devices are reached via their instance + where: { TeamId, ProjectId: null, ApplicationId: { [Op.ne]: null } }, + attributes: ['id', 'name', 'ApplicationId'], + order: [['name', 'ASC']] + }) + ]) + + const result = { + self: null, + applications: applications.map(application => { + return { + id: application.hashid, + name: application.name, + instances: instances.filter(i => i.ApplicationId === application.id).map(i => { + return { id: i.id, name: i.name } + }), + devices: devices.filter(d => d.ApplicationId === application.id).map(d => { + return { id: `dev:${d.hashid}`, name: d.name } + }) + } + }) + } + + // Tell the caller which application it belongs to so it can build + // application scoped topics + if (ownerType === 'project') { + const self = instances.find(i => i.id === request.session.ownerId) + if (self) { + result.self = { id: self.id, applicationId: app.db.models.Application.encodeHashid(self.ApplicationId) } + } + } else { + const device = await app.db.models.Device.findOne({ + where: { id: request.session.ownerId }, + attributes: ['id', 'ProjectId', 'ApplicationId'] + }) + if (device?.ProjectId) { + const owner = instances.find(i => i.id === device.ProjectId) + if (owner) { + result.self = { id: owner.id, applicationId: app.db.models.Application.encodeHashid(owner.ApplicationId) } + } + } else if (device?.ApplicationId) { + result.self = { id: `dev:${device.hashid}`, applicationId: app.db.models.Application.encodeHashid(device.ApplicationId) } + } + } + + reply.send(result) + }) +} diff --git a/test/unit/forge/comms/authRoutes_spec.js b/test/unit/forge/comms/authRoutes_spec.js index 88951be6db..decadf0922 100644 --- a/test/unit/forge/comms/authRoutes_spec.js +++ b/test/unit/forge/comms/authRoutes_spec.js @@ -605,6 +605,76 @@ describe('Broker Auth API', async function () { topic: 'ff/v1/abc/p/another-project/res-random/foo/bar' }) }) + it('allows project to publish to an app owned device inbox', async function () { + await allowWrite({ + username: 'project:abc:xyz', + topic: 'ff/v1/abc/p/dev:some-device/in/foo' + }) + }) + describe('application scoped broadcast', async function () { + let projectUsername + let appTopicPrefix + before(async function () { + projectUsername = `project:${TestObjects.ATeam.hashid}:${TestObjects.ProjectA.id}` + appTopicPrefix = `ff/v1/${TestObjects.ATeam.hashid}/a/${TestObjects.ApplicationA.hashid}/p` + }) + it('allows project to publish to own application broadcast topic', async function () { + await allowWrite({ + username: projectUsername, + topic: `${appTopicPrefix}/${TestObjects.ProjectA.id}/out/foo` + }) + await allowWrite({ + username: projectUsername, + topic: `${appTopicPrefix}/${TestObjects.ProjectA.id}/out/foo/bar` + }) + }) + it('prevents project from publishing as another source', async function () { + await denyWrite({ + username: projectUsername, + topic: `${appTopicPrefix}/another-project/out/foo` + }) + await denyWrite({ + username: projectUsername, + topic: `${appTopicPrefix}/dev:some-device/out/foo` + }) + }) + it('prevents project from publishing to another application broadcast topic', async function () { + await denyWrite({ + username: projectUsername, + topic: `ff/v1/${TestObjects.ATeam.hashid}/a/another-application/p/${TestObjects.ProjectA.id}/out/foo` + }) + }) + it('allows project to subscribe to own application broadcasts', async function () { + await allowRead({ + username: projectUsername, + topic: `${appTopicPrefix}/+/out/foo` + }) + await allowRead({ + username: projectUsername, + topic: `${appTopicPrefix}/dev:some-device/out/foo` + }) + await allowRead({ + username: projectUsername, + topic: `$share/${TestObjects.ProjectA.id}/${appTopicPrefix}/+/out/foo` + }) + }) + it('prevents project from subscribing to another application broadcasts', async function () { + await denyRead({ + username: projectUsername, + topic: `ff/v1/${TestObjects.ATeam.hashid}/a/another-application/p/+/out/foo` + }) + await denyRead({ + username: projectUsername, + topic: `ff/v1/${TestObjects.ATeam.hashid}/a/+/p/+/out/foo` + }) + }) + it('prevents project in another team subscribing to application broadcasts', async function () { + await denyRead({ + username: `project:another-team:${TestObjects.ProjectA.id}`, + topic: `${appTopicPrefix}/+/out/foo` + }) + }) + }) }) }) @@ -758,6 +828,28 @@ describe('Broker Auth API', async function () { topic: `ff/v1/${TestObjects.ATeam.hashid}/p/${TestObjects.ProjectB.id}/res/foo` }) }) + it('cannot subscribe to own inbox if unassigned', async function () { + await denyRead({ + username: deviceUsername, + topic: `ff/v1/${TestObjects.ATeam.hashid}/p/dev:${TestObjects.DeviceA.hashid}/in/foo` + }) + }) + it('cannot publish to app owned device inbox if unassigned', async function () { + await denyWrite({ + username: deviceUsername, + topic: `ff/v1/${TestObjects.ATeam.hashid}/p/dev:${TestObjects.DeviceB.hashid}/in/foo` + }) + }) + it('cannot use application scoped broadcast if unassigned', async function () { + await denyRead({ + username: deviceUsername, + topic: `ff/v1/${TestObjects.ATeam.hashid}/a/${TestObjects.ApplicationA.hashid}/p/+/out/foo` + }) + await denyWrite({ + username: deviceUsername, + topic: `ff/v1/${TestObjects.ATeam.hashid}/a/${TestObjects.ApplicationA.hashid}/p/dev:${TestObjects.DeviceA.hashid}/out/foo` + }) + }) }) describe('assigned to instance', async function () { before(async function () { @@ -812,9 +904,62 @@ describe('Broker Auth API', async function () { topic: `ff/v1/${TestObjects.ATeam.hashid}/p/${TestObjects.ProjectB.id}/res/foo` }) }) + it('can publish to HA project response if assigned', async function () { + await allowWrite({ + username: deviceUsername, + topic: `ff/v1/${TestObjects.ATeam.hashid}/p/${TestObjects.ProjectB.id}/res-abcd1234/foo` + }) + }) + it('can publish to app owned device inbox and response if assigned', async function () { + await allowWrite({ + username: deviceUsername, + topic: `ff/v1/${TestObjects.ATeam.hashid}/p/dev:${TestObjects.DeviceB.hashid}/in/foo` + }) + await allowWrite({ + username: deviceUsername, + topic: `ff/v1/${TestObjects.ATeam.hashid}/p/dev:${TestObjects.DeviceB.hashid}/res/foo` + }) + }) + it('cannot subscribe to app owned device inbox', async function () { + await denyRead({ + username: deviceUsername, + topic: `ff/v1/${TestObjects.ATeam.hashid}/p/dev:${TestObjects.DeviceA.hashid}/in/foo` + }) + }) + it('can use application scoped broadcast of its instance application', async function () { + await allowRead({ + username: deviceUsername, + topic: `ff/v1/${TestObjects.ATeam.hashid}/a/${TestObjects.ApplicationA.hashid}/p/+/out/foo` + }) + await allowWrite({ + username: deviceUsername, + topic: `ff/v1/${TestObjects.ATeam.hashid}/a/${TestObjects.ApplicationA.hashid}/p/${TestObjects.ProjectA.id}/out/foo` + }) + }) + it('cannot publish application scoped broadcast as another source', async function () { + await denyWrite({ + username: deviceUsername, + topic: `ff/v1/${TestObjects.ATeam.hashid}/a/${TestObjects.ApplicationA.hashid}/p/dev:${TestObjects.DeviceA.hashid}/out/foo` + }) + await denyWrite({ + username: deviceUsername, + topic: `ff/v1/${TestObjects.ATeam.hashid}/a/${TestObjects.ApplicationA.hashid}/p/${TestObjects.ProjectB.id}/out/foo` + }) + }) }) describe('assigned to application', async function () { before(async function () { + // Remove device from the instance it was assigned to above. Assigning + // to an application does not clear the instance, so the device would + // otherwise remain instance owned + await app.inject({ + method: 'PUT', + url: `/api/v1/devices/${TestObjects.DeviceA.hashid}`, + body: { + instance: null + }, + cookies: { sid: TestObjects.tokens.alice } + }) // Assign device to application await app.inject({ method: 'PUT', @@ -824,6 +969,8 @@ describe('Broker Auth API', async function () { }, cookies: { sid: TestObjects.tokens.alice } }) + const owner = await app.db.models.Device.getOwnerTypeAndId(TestObjects.DeviceA.hashid) + owner.should.have.property('ownerType', 'application') }) it('can subscribe to application command', async function () { await allowRead({ @@ -884,6 +1031,63 @@ describe('Broker Auth API', async function () { username: deviceUsername, topic: `ff/v1/${TestObjects.ATeam.hashid}/p/${TestObjects.ProjectB.id}/res/foo` }) + await allowWrite({ + username: deviceUsername, + topic: `ff/v1/${TestObjects.ATeam.hashid}/p/${TestObjects.ProjectB.id}/res-abcd1234/foo` + }) + }) + it('can subscribe to own inbox', async function () { + await allowRead({ + username: deviceUsername, + topic: `ff/v1/${TestObjects.ATeam.hashid}/p/dev:${TestObjects.DeviceA.hashid}/in/foo` + }) + }) + it('cannot subscribe to another device inbox', async function () { + await denyRead({ + username: deviceUsername, + topic: `ff/v1/${TestObjects.ATeam.hashid}/p/dev:${TestObjects.DeviceB.hashid}/in/foo` + }) + }) + it('can publish to another device inbox and response', async function () { + await allowWrite({ + username: deviceUsername, + topic: `ff/v1/${TestObjects.ATeam.hashid}/p/dev:${TestObjects.DeviceB.hashid}/in/foo` + }) + await allowWrite({ + username: deviceUsername, + topic: `ff/v1/${TestObjects.ATeam.hashid}/p/dev:${TestObjects.DeviceB.hashid}/res/foo` + }) + }) + it('can use own application scoped broadcast', async function () { + await allowRead({ + username: deviceUsername, + topic: `ff/v1/${TestObjects.ATeam.hashid}/a/${TestObjects.ApplicationA.hashid}/p/+/out/foo` + }) + await allowWrite({ + username: deviceUsername, + topic: `ff/v1/${TestObjects.ATeam.hashid}/a/${TestObjects.ApplicationA.hashid}/p/dev:${TestObjects.DeviceA.hashid}/out/foo` + }) + }) + it('cannot use another application scoped broadcast', async function () { + const otherApplication = await TestObjects.DeviceB.getApplication() + await denyRead({ + username: deviceUsername, + topic: `ff/v1/${TestObjects.ATeam.hashid}/a/${otherApplication.hashid}/p/+/out/foo` + }) + await denyWrite({ + username: deviceUsername, + topic: `ff/v1/${TestObjects.ATeam.hashid}/a/${otherApplication.hashid}/p/dev:${TestObjects.DeviceA.hashid}/out/foo` + }) + }) + it('cannot publish application scoped broadcast as another source', async function () { + await denyWrite({ + username: deviceUsername, + topic: `ff/v1/${TestObjects.ATeam.hashid}/a/${TestObjects.ApplicationA.hashid}/p/dev:${TestObjects.DeviceB.hashid}/out/foo` + }) + await denyWrite({ + username: deviceUsername, + topic: `ff/v1/${TestObjects.ATeam.hashid}/a/${TestObjects.ApplicationA.hashid}/p/${TestObjects.ProjectA.id}/out/foo` + }) }) }) describe('device log topics', async function () { diff --git a/test/unit/forge/ee/routes/projectLink/index_spec.js b/test/unit/forge/ee/routes/projectLink/index_spec.js new file mode 100644 index 0000000000..d6ea078edb --- /dev/null +++ b/test/unit/forge/ee/routes/projectLink/index_spec.js @@ -0,0 +1,142 @@ +const should = require('should') // eslint-disable-line + +const setup = require('../../setup') + +describe('Project Link API', function () { + let app + const TestObjects = { tokens: {} } + + async function login (username, password) { + const response = await app.inject({ + method: 'POST', + url: '/account/login', + payload: { username, password, remember: false } + }) + response.cookies.should.have.length(1) + TestObjects.tokens[username] = response.cookies[0].value + } + + async function getTargets (teamId, token) { + return app.inject({ + method: 'GET', + url: `/api/v1/teams/${teamId}/project-link/targets`, + headers: { Authorization: `Bearer ${token}` } + }) + } + + before(async function () { + app = await setup() + await login('alice', 'aaPassword') + + TestObjects.application2 = await app.factory.createApplication({ name: 'application-2' }, app.team) + TestObjects.instance2 = await app.factory.createInstance( + { name: 'project2' }, + TestObjects.application2, + app.stack, + app.template, + app.projectType, + { start: false } + ) + TestObjects.appDevice = await app.factory.createDevice({ name: 'app-device', type: 'pi' }, app.team, null, TestObjects.application2) + TestObjects.instanceDevice = await app.factory.createDevice({ name: 'instance-device' }, app.team, app.instance) + TestObjects.unassignedDevice = await app.factory.createDevice({ name: 'unassigned-device' }, app.team) + + TestObjects.tokens.project = (await app.instance.refreshAuthTokens()).token + // get db Devices with all associations (refreshAuthTokens needs device.Team) + TestObjects.tokens.appDevice = (await (await app.db.models.Device.byId(TestObjects.appDevice.id)).refreshAuthTokens()).token + TestObjects.tokens.instanceDevice = (await (await app.db.models.Device.byId(TestObjects.instanceDevice.id)).refreshAuthTokens()).token + TestObjects.tokens.unassignedDevice = (await (await app.db.models.Device.byId(TestObjects.unassignedDevice.id)).refreshAuthTokens()).token + TestObjects.tokens.alicePAT = (await app.db.controllers.AccessToken.createPersonalAccessToken(app.user, '', null, 'alice-pat')).token + + TestObjects.team2 = await app.factory.createTeam({ name: 'BTeam' }) + const team2Device = await app.factory.createDevice({ name: 'team2-device' }, TestObjects.team2) + TestObjects.tokens.team2Device = (await (await app.db.models.Device.byId(team2Device.id)).refreshAuthTokens()).token + }) + + after(async function () { + await app.close() + }) + + it('lists applications with their instances and app owned devices for a project token', async function () { + const response = await getTargets(app.team.hashid, TestObjects.tokens.project) + response.statusCode.should.equal(200) + const result = response.json() + + Object.keys(result).should.eql(['self', 'applications']) + result.should.have.property('self', { id: app.instance.id, applicationId: app.application.hashid }) + result.applications.should.have.length(2) + + const app1 = result.applications.find(a => a.id === app.application.hashid) + app1.should.have.property('name', 'application-1') + app1.instances.should.eql([{ id: app.instance.id, name: app.instance.name }]) + // instance owned devices are reached via their instance so are not listed + app1.devices.should.have.length(0) + + const app2 = result.applications.find(a => a.id === TestObjects.application2.hashid) + app2.instances.should.eql([{ id: TestObjects.instance2.id, name: 'project2' }]) + app2.devices.should.eql([{ id: `dev:${TestObjects.appDevice.hashid}`, name: 'app-device' }]) + }) + + it('returns the app owned device identity for a device token', async function () { + const response = await getTargets(app.team.hashid, TestObjects.tokens.appDevice) + response.statusCode.should.equal(200) + response.json().should.have.property('self', { id: `dev:${TestObjects.appDevice.hashid}`, applicationId: TestObjects.application2.hashid }) + }) + + it('returns the owning instance identity for an instance owned device token', async function () { + const response = await getTargets(app.team.hashid, TestObjects.tokens.instanceDevice) + response.statusCode.should.equal(200) + response.json().should.have.property('self', { id: app.instance.id, applicationId: app.application.hashid }) + }) + + it('returns no identity for an unassigned device token', async function () { + const response = await getTargets(app.team.hashid, TestObjects.tokens.unassignedDevice) + response.statusCode.should.equal(200) + const result = response.json() + result.should.have.property('self', null) + const deviceIds = result.applications.flatMap(a => a.devices.map(d => d.id)) + deviceIds.should.not.containEql(`dev:${TestObjects.unassignedDevice.hashid}`) + }) + + it('rejects a project token for another team', async function () { + const response = await getTargets(TestObjects.team2.hashid, TestObjects.tokens.project) + response.statusCode.should.equal(404) + }) + + it('rejects a device token for another team', async function () { + const response = await getTargets(app.team.hashid, TestObjects.tokens.team2Device) + response.statusCode.should.equal(404) + }) + + it('rejects a user session', async function () { + const response = await app.inject({ + method: 'GET', + url: `/api/v1/teams/${app.team.hashid}/project-link/targets`, + cookies: { sid: TestObjects.tokens.alice } + }) + response.statusCode.should.equal(403) + }) + + it('rejects a personal access token', async function () { + const response = await getTargets(app.team.hashid, TestObjects.tokens.alicePAT) + response.statusCode.should.equal(403) + }) + + it('rejects a request without credentials', async function () { + const response = await app.inject({ + method: 'GET', + url: `/api/v1/teams/${app.team.hashid}/project-link/targets` + }) + response.statusCode.should.equal(401) + }) + + it('returns 404 when project communication is disabled', async function () { + app.config.features.register('projectComms', false, false) + try { + const response = await getTargets(app.team.hashid, TestObjects.tokens.project) + response.statusCode.should.equal(404) + } finally { + app.config.features.register('projectComms', true, false) + } + }) +}) From 65c683db8e0f3461d3cfefbf2bf409afa2116e5b Mon Sep 17 00:00:00 2001 From: Steve-Mcl Date: Thu, 29 Oct 2026 11:31:59 +0000 Subject: [PATCH 2/4] add clarifying comments to acls --- forge/comms/aclManager.js | 36 ++++++++++++++++++++++-------- forge/ee/lib/projectComms/index.js | 9 ++++++++ 2 files changed, 36 insertions(+), 9 deletions(-) diff --git a/forge/comms/aclManager.js b/forge/comms/aclManager.js index 585d40cc38..8404b84099 100644 --- a/forge/comms/aclManager.js +++ b/forge/comms/aclManager.js @@ -135,22 +135,40 @@ module.exports = function (app) { return false } }, - checkClientInApplication: async function (requestParts, ids, acl) { + checkClientInApplication: async function (requestParts, usernameParts, acl) { // requestParts = [ _ , , , ] - // ids = [ 'project', , ] or [ 'device', , ] + // the regex match of the requested topic (ff/v1//a//p//out/...), + // i.e. what the client is asking to sub/pub to + // usernameParts = [ 'project', , ] or [ 'device', , ] + // the connecting client's broker username split on ':' + // + // Used by 4 ACLs (2 project, 2 device), all on the topic ff/v1//a//p//out/+/# + // a = the application the broadcast is scoped to + // p = the sender: an instance id, or dev: for an application owned device + // + // Receive application scoped broadcasts (project sub, device sub - ff/v1//a//p/+/out/+/#): + // A project node in application A may only receive broadcasts scoped to application A, i.e. the + // client (instance, or device via its owner) must belong to . Any sender in A is allowed. + // + // Send application scoped broadcasts (project pub, device pub - ff/v1//a//p//out/+/#): + // As above, the client must belong to , and acl.checkSource also requires + // to be the client itself so it cannot publish as another member: + // - instance: = its instance id + // - instance owned device: = its owning instance's id (it broadcasts as its instance) + // - application owned device: = dev: // Do the simple team id check - if (requestParts[1] !== ids[1]) { + if (requestParts[1] !== usernameParts[1]) { return false } let applicationId let sourceId try { - if (ids[0] === 'project') { - applicationId = await app.db.models.Project.getProjectApplicationId(ids[2]) - sourceId = ids[2] - } else if (ids[0] === 'device') { - const assignedTo = await app.db.models.Device.getOwnerTypeAndId(ids[2]) + if (usernameParts[0] === 'project') { + applicationId = await app.db.models.Project.getProjectApplicationId(usernameParts[2]) + sourceId = usernameParts[2] + } else if (usernameParts[0] === 'device') { + const assignedTo = await app.db.models.Device.getOwnerTypeAndId(usernameParts[2]) if (assignedTo?.ownerType === 'instance') { // An instance owned device is part of its instance's application // and broadcasts using its instance id @@ -158,7 +176,7 @@ module.exports = function (app) { sourceId = assignedTo.ownerId } else if (assignedTo?.ownerType === 'application') { applicationId = assignedTo.ownerId - sourceId = `dev:${ids[2]}` + sourceId = `dev:${usernameParts[2]}` } } } catch (err) { diff --git a/forge/ee/lib/projectComms/index.js b/forge/ee/lib/projectComms/index.js index 56f9bfea62..ff23e50d00 100644 --- a/forge/ee/lib/projectComms/index.js +++ b/forge/ee/lib/projectComms/index.js @@ -53,6 +53,8 @@ module.exports.init = function (app) { ) // Receive application scoped broadcasts from members of this project's application // - ff/v1//a//p/+/out/+/# + // a = the application the broadcast is scoped to (must be this project's application) + // p = the sender: an instance id, or dev: for an application owned device app.comms.aclManager.addACL( 'project', 'sub', @@ -60,6 +62,8 @@ module.exports.init = function (app) { ) // Send application scoped broadcast messages // - ff/v1//a//p//out/+/# + // a = this project's application + // p = this project's id (the sender) app.comms.aclManager.addACL( 'project', 'pub', @@ -147,6 +151,8 @@ module.exports.init = function (app) { ) // Receive application scoped broadcasts from members of this device's application // - ff/v1//a//p/+/out/+/# + // a = the application the broadcast is scoped to (must be this device's application) + // p = the sender: an instance id, or dev: for an application owned device app.comms.aclManager.addACL( 'device', 'sub', @@ -154,6 +160,9 @@ module.exports.init = function (app) { ) // Send application scoped broadcast messages // - ff/v1//a//p//out/+/# + // a = this device's application (via its instance, if instance owned) + // p = the sender: the owning instance's id for an instance owned device, + // or dev: for an application owned device app.comms.aclManager.addACL( 'device', 'pub', From b15c380cafc23dd16cfeb2714c9082c154309ec0 Mon Sep 17 00:00:00 2001 From: Steve-Mcl Date: Thu, 29 Oct 2026 12:11:32 +0000 Subject: [PATCH 3/4] fix device application assignment in authRoutesV2 spec --- test/unit/forge/comms/authRoutesV2_spec.js | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/test/unit/forge/comms/authRoutesV2_spec.js b/test/unit/forge/comms/authRoutesV2_spec.js index abea519d3b..d948cb18c3 100644 --- a/test/unit/forge/comms/authRoutesV2_spec.js +++ b/test/unit/forge/comms/authRoutesV2_spec.js @@ -866,6 +866,17 @@ describe('Broker Auth v2 API', async function () { }) describe('assigned to application', async function () { before(async function () { + // Remove device from the instance it was assigned to above. Assigning + // to an application does not clear the instance, so the device would + // otherwise remain instance owned + await app.inject({ + method: 'PUT', + url: `/api/v1/devices/${TestObjects.DeviceA.hashid}`, + body: { + instance: null + }, + cookies: { sid: TestObjects.tokens.alice } + }) // Assign device to application await app.inject({ method: 'PUT', @@ -875,6 +886,8 @@ describe('Broker Auth v2 API', async function () { }, cookies: { sid: TestObjects.tokens.alice } }) + const owner = await app.db.models.Device.getOwnerTypeAndId(TestObjects.DeviceA.hashid) + owner.should.have.property('ownerType', 'application') }) it('can subscribe to application command', async function () { await allowRead({ From 99c4656f9c5c99575be38c6068ff60d76b6a5d9f Mon Sep 17 00:00:00 2001 From: Stephen McLaughlin <44235289+Steve-Mcl@users.noreply.github.com> Date: Fri, 30 Oct 2026 17:10:22 +0000 Subject: [PATCH 4/4] Remove duplicate sentence in projectnodes.md --- docs/user/projectnodes.md | 6 ------ 1 file changed, 6 deletions(-) diff --git a/docs/user/projectnodes.md b/docs/user/projectnodes.md index 4055afe13f..9b1e6fcaa5 100644 --- a/docs/user/projectnodes.md +++ b/docs/user/projectnodes.md @@ -85,12 +85,6 @@ target instance must be running and have a `Project In` node listening on the sa topic. Because every call travels through the platform's broker, logic called this way is unavailable to a caller whose connection to the platform is down. -**Calls need the target to be up.** The `Project Call` node waits for the default -timeout of 30 seconds, then logs an error that can be caught with a Catch node. The -target instance must be running and have a `Project In` node listening on the same -topic. Because every call travels through the platform's broker, logic called this -way is unavailable to a caller whose connection to the platform is down. - **Load is shared only in HA mode.** The instance holding the called flows serves every caller from a single Node-RED runtime. In [High Availability mode](./high-availability.md) the nodes automatically switch to MQTT shared subscriptions, so calls are distributed